Jam

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

The annotations already declare write, idempotent, open-world, and destructive hints, and the description adds useful behavior: duplicate reactions are no-ops, the author may be emailed, and the reaction is visible wherever the comment is shared. It does not explain why destructiveHint is true, but it does not contradict that annotation.

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 front-loaded with the purpose and keeps usefulness and side-effect notes concise. The emoji list is somewhat redundant because the same enum and meanings are in the schema, but the overall structure is clear and not bloated.

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 add-reaction tool with full schema coverage and annotations, the description covers purpose, a representative use case, permissions, duplicate behavior, and notification/visibility side effects. It omits return-value or error behavior, but the core information needed to invoke it correctly is 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 100%, so the schema already explains commentId, emoji, intent, and llm_model. The description repeats the emoji meanings already present in the schema enum description and adds no further guidance for the other parameters, so the baseline score 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?

The description states a specific verb and resource: react to a comment on a Jam, and it clarifies scope by saying it works on anyone's comment, not just your own. It is clear without opening the schema, though it does not explicitly compare itself to sibling tools such as removeReaction or createComment.

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 a clear usage context: useful for acknowledging a comment you've already acted on, and it clarifies that it works on anyone's comment. It does not state when not to use it or point to removeReaction for undoing a reaction, so it stops short of full alternative-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?

Beyond the annotations it discloses the permission requirement ('Needs the permission that edits a Jam's title'), the security-relevant side effect that the URL becomes visible on a possibly public share page, the credential-rejection rule, and the return value ('Returns the resource'). The idempotency statement merely restates idempotentHint, but the remaining context is substantive and consistent with readOnlyHint=false and destructiveHint=false.

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, label guidance, idempotency, visibility warning, and permissions arrive in a logical order with the core action front-loaded. It is slightly long, and the motivational 'record proof of your work' sentence overlaps with the opening examples, but no sentence is pure 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 mutation tool with no output schema, the definition covers what is created, what is returned, permissions, idempotency, public-visibility risk, and input rejection rules. An agent has everything needed to decide to call it and to construct valid, safe arguments.

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: it explains when a `label` is needed and what happens without one (viewers see the host and path), and it constrains `url` beyond the schema by forbidding token-bearing or credentialed URLs. The meta-parameters intent and llm_model are left to their 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?

The description opens with a specific verb and resource: 'Attach a URL to a Jam', and gives concrete examples of what a URL can be (pull request, CI run, another Jam). It does not differentiate itself from the inverse sibling removeResource or clarify its relationship to updateJam, so it stops short of the top mark.

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

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

It provides a clear when-to-use rule ('When you record proof of your work, add the pull request or ticket it proves as a resource') and a strong when-not-to: do not pass URLs carrying tokens, and URLs with user/password are refused. It never names an alternative tool (e.g. removeResource for detaching), so there is no explicit alternative 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?

The annotations already declare this tool as read-only, idempotent, non-destructive, and deprecated via the title. The description adds a concrete replacement path, which is useful, but it does not describe other behavioral traits such as what the analysis did or how it behaved before deprecation.

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

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

The description is a single front-loaded sentence with no wasted wording. It communicates deprecation and the replacement immediately.

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 deprecated redirect tool, the description is nearly complete: it tells the agent not to use this tool and what to use instead. It does not explain the legacy tool's return behavior, but that is a minor gap given the deprecation notice.

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 in the input schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable given complete schema coverage.

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

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

The description identifies the tool as deprecated and points to a replacement, which helps distinguish it from getFrames. However, it never states what analyzeVideo itself does beyond what the tool name implies, so the actual purpose remains vague.

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 migration guidance: use getFrames with mode "overview" instead. For a deprecated tool, this is exactly the usage instruction an agent needs and leaves little ambiguity about avoiding this 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?

Adds real behavior beyond the annotations: email notifications to other users, visibility scoped to Jam access including public viewers, and the constraint that replies are one level deep and ignore playbackRelativeTimestamp. It does not describe what the call returns (e.g., the new comment id), which is the one notable 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-loads the action, then threading rules, then use cases and side effects — a sensible ordering. The closing sentence on email notification and sharing visibility is slightly wordy but carries real information, so nothing is clearly 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 6-parameter mutation tool with no output schema, the description covers scope, threading, mentions, and notification side effects well. The missing piece is the response shape — an agent cannot tell whether the created comment id is returned or must be re-fetched via getDetails.

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 genuine meaning: parentId must come from getDetails and must be a top-level comment id, and playbackRelativeTimestamp is silently ignored when parentId is set. That interaction is not expressible in the schema alone.

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

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

States a specific verb and resource ("Add a new comment to a Jam bug report") and immediately clarifies threading scope. The action is instantly distinguishable from siblings editComment, deleteComment, and addReaction 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 concrete use cases ("add notes, analysis results, or follow-up information") and routes the agent for threading: use parentId via getDetails, and listMembers for mention userIds. It does not explicitly contrast with editComment/deleteComment, so the "when not to use" side is only implied.

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

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

Goes well beyond the annotations by disclosing non-obvious side effects: permission self-upgrade from Viewer to Creator, seat billing impact, and admin notification emails. It also discloses return values (id and shortId) that the absence of an output schema would otherwise leave unknown, and warns about non-unique names.

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, each carrying distinct information: what it does and returns, the deduplication caveat, and the side effects. The primary purpose and the immediate follow-up path are front-loaded 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 mutating tool with no output schema, the description covers return shape, side effects, and the prerequisite check. Nothing an agent needs to invoke it safely is missing, and the destructiveHint=true annotation is consistent with the billing/email side effects described.

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 parameter definitions already carry their own meaning. The description nevertheless adds real semantics for 'name' — that names are not unique and duplicates are permitted — which the schema's length constraint 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 and resource plus scope: "Create a folder in the team to organize Jams into." It also distinguishes itself from listFolders (reuse case) and updateJam (the follow-up filing call), so an agent can place it among 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 when-not plus the alternative: "call listFolders first if you mean to reuse an existing folder rather than add another one with the same name." It also tells the agent what to do next (updateJam) after creation, leaving no routing ambiguity.

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

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

Goes well beyond the annotations by disclosing consequential side effects: possible Viewer-to-Creator promotion, seat billing impact, admin emails, and a recording-link-created webhook emission. The important caveat — omitting recordingUrlId yields a link that captures NO console/network logs — is stated twice, once in the lead and once in the IMPORTANT block, which is somewhat redundant but not contradictory to destructiveHint/openWorldHint.

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 riskiest detail (log capture) follows immediately, which matches how an agent should read it. It runs long and repeats the no-logs consequence in both the lead and the IMPORTANT block, so a bit of trimming would help.

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 9-parameter creation tool with no output schema and real org-level side effects (billing, roles, webhooks), the description supplies the missing prerequisites, the failure branch, and the consequences. An agent has everything needed to act correctly or escalate to the user.

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 nonetheless highlights which parameters actually change outcomes — that folder/expiresAt are optional targeting, and that recordingUrlId is the decisive one for log capture, with the consequence of omission spelled out. It does not explain the folder identifier formats (name/ID/root) or metadata limits, which remain schema-only.

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 and its scope: "Create a reusable recording link that lets anyone with the URL record and submit a new Jam." It also implicitly separates itself from updateRecordingLink/listRecordingLinks by describing creation plus optional folder/expiry targeting, so an agent can distinguish it from the sibling set.

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 workflow — "Before creating, call listRecordingUrls and ask the user which connected domain to record from — don't guess" — naming the exact sibling to call first. It also covers the negative branch: if no connected domains exist, warn the user and point to the dashboard URL rather than silently proceeding.

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, but the description adds behavior they cannot express: the cascade to attachments, the author-only authorization rule, the non-recoverable nature, and a confirm-first requirement. These are exactly the kinds of consequences an agent needs before firing an irreversible write.

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

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

Three tight sentences, front-loaded with the action and its blast radius, then authorization, then ID sourcing. Nothing is padding and the destructive warning is not 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?

For a single-required-param destructive tool with no output schema, this covers what is removed, who may remove it, and irreversibility. It does not say what happens on a repeat or failed call (missing comment, wrong author), which matters given idempotentHint=true.

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 commentUid is already documented as coming from createComment or getDetails, so the description's sentence on ID provenance largely restates the schema. The intent and llm_model parameters are not addressed at all, though the schema covers them adequately.

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

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

States a specific verb and resource ("Delete a comment from a Jam") plus a scope detail that changes expectations: attachments are removed too. An agent can distinguish it from editComment and from deleteJam 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 a concrete prerequisite ("Only the comment's own author can delete it"), an ID source (createComment result or getDetails), and an operational instruction ("confirm with the user before calling"). It stops short of an explicit either/or against editComment, e.g. "to retract wording but keep the thread, use editComment," so it misses the top band.

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 mark this as destructive and non-read-only, but the description adds critical context beyond them: there is no trash or archive view, the Jams leave team lists and search, nobody can restore them, and the call returns archivedJamCount. It also warns not to tell users the Jams can be restored, which is exactly the kind of behavioral guidance an agent needs for an irreversible operation.

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

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

The description is front-loaded with the destructive scope, then the irreversibility, then the return value, then the operational warnings. Every sentence carries necessary information for a destructive tool, and there is no redundant restatement of the title or annotations.

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 folder-deletion tool with no output schema, the description covers the cascade effect, irreversibility, required confirmation, prerequisite listing step, identifier constraints, and return value. Nothing an agent needs in order 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance beyond the schema by emphasizing that folderId must come from listFolders and must never be a folder name because a name could match the wrong folder. It does not explain the intent or llm_model parameters, but those are already documented in the schema.

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

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

The description states a specific verb and resource ("Delete a folder") and immediately clarifies the scope: every Jam inside it is deleted too. It distinguishes this from sibling tools like deleteJam and listFolders by explaining the folder-level cascade and the return value.

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

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

It explicitly says to confirm with the user before calling, to use listFolders first so the user can see the folder contents, and to pass a folder ID or short ID rather than a name. These are concrete when-to-use and how-to-use instructions with a named alternative for inspection.

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, but the description goes well beyond them: it explains what is actually lost (team lists, search results), that no trash or archive view exists for restoration, and even constrains what the agent may tell the user afterwards. This is unusually rich behavioral context for a mutation tool.

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

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

Three short sentences, each earning its place: what it does, what is lost and why it is irreversible, and the confirmation obligation. The consequence is front-loaded before the caution.

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 destructive tool with no output schema, the description covers effect, irreversibility, and user-communication obligations. It does not mention failure modes such as an unknown jamId or missing permissions, which is a minor gap given the otherwise thorough disclosure.

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%, with jamId, intent, and llm_model all documented inline, including the UUID-or-jam.dev-URL format. The description adds no parameter-level meaning 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 ("Delete a Jam") and immediately describes the observable effect: it disappears from the team's lists and search results. The resource is unambiguous against siblings like deleteFolder, deleteComment, and updateJam, so an agent can select it 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 precondition for invocation — confirm with the user before calling — and a post-call communication rule. It does not name an alternative (e.g., updateJam if the user only wants to change something) or state when deletion is inappropriate, 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?

Goes well beyond the annotations: it discloses that the delete is soft, that existing Jams recorded through the link survive, exactly what is returned (publicId and deletedAt), and how the three failure shapes (unknown, already-deleted, other team's ID) all surface as not-found. This is the kind of consequence detail an agent needs before a destructive call.

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 action and the soft-delete caveat, then the return value, then the error contract. Nothing is repeated from the annotations and nothing 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?

With no output schema, the description takes on return-value duty and does so precisely (publicId, deletedAt), and it closes the loop on error behavior. For a single-parameter destructive tool, an agent has everything needed to call it and interpret the result.

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 about the required publicId: an already-deleted or cross-team ID yields not-found rather than a silent success, which matters for a call annotated non-idempotent. The optional intent and llm_model parameters get no mention, but they are self-documented.

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

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

States a specific verb and resource ('Delete a recording link by its publicId') plus the effect ('stops accepting new recordings'), which cleanly separates it from deleteJam and deleteFolder. It does not explicitly name a sibling, so it stops short of the top score.

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

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

The description gives the condition under which the tool is appropriate (you want to stop the link accepting new recordings, without affecting existing Jams), which implicitly routes an agent away from deleteJam. It never names an alternative or a when-not case explicitly, so guidance remains inferred.

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, and the description earns credit by specifying exactly what is destroyed: "The new body replaces the old one entirely." It further discloses the authorization requirement (author-only), the content format (Markdown), and the visibility consequence to other users including public viewers.

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 sentences, front-loaded with the core action and rationale, and each carries distinct information (purpose, input lineage, replacement semantics, permissions/visibility). Slightly redundant that both the description and the schema state the body fully replaces the old one.

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

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

For a mutation tool with no output schema, the description covers the critical unknowns: what is overwritten, who may call it, and who sees the result. It does not mention failure modes (invalid commentId, non-authored comment) or what the tool returns on success, a minor gap given the operation'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 commentId, body, intent, and llm_model are already documented in the schema. The description only restates that commentId comes from createComment and that body is Markdown replacement text, adding no syntax or edge-case detail beyond the structured fields. 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 ("Rewrite a comment you previously left on a Jam") plus scope (own comments only), which separates it cleanly from createComment and deleteComment in the sibling list. The parenthetical purpose ("correct or extend its own note instead of stacking a follow-up comment") makes the distinction unmistakable.

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

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

Gives clear when-to-use guidance: correct or extend an existing note rather than posting a follow-up. It also states a hard eligibility constraint ("You can only edit comments you authored"). It never explicitly names createComment or deleteComment as the alternative for other cases, so the routing is implied 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile requires no description support. The description does add return-field disclosure (id, title, url, text), valuable since there is no output schema, but the parenthetical "(what getDetails returns)" is ambiguous about whether fetch duplicates getDetails output or just its text field.

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 compact sentence plus a routing clause — no padding, and the return shape is front-loaded. The trailing parenthetical is cryptic enough that it slightly undercuts the otherwise tight structure.

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

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

For a simple one-required-param read with no output schema, the description covers the return payload and points to getDetails. The key unresolved question — why fetch exists when getDetails exists, and whether their outputs overlap — is exactly what an agent needs to choose correctly, and it is not answered.

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 id (UUID or jam.dev URL) and the intent/llm_model telemetry params are already fully documented. The description adds no syntax or format meaning 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?

"A Jam as a citable document: id, title, url and text" states the resource and exactly what comes back, which makes it distinguishable from the raw-detail siblings. It falls short of 5 because it is a noun phrase rather than a verb+resource statement, so the action (retrieve) is only inferable from the tool name "fetch".

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 getDetails to investigate" names the alternative, which is real routing guidance. However, the selecting condition is left implicit — the agent must guess that fetch is for citation/summary and getDetails for deeper inspection, and there is no guidance on when neither applies.

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 safe, idempotent read, so the description correctly spends its space on behavior the annotations cannot convey: server-side filtering, a leading match-count line, and a `More:` line carrying the next-page cursor. It does not discuss default ordering or what happens with an expired cursor, which is a minor residual 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?

Two sentences, front-loaded with the output format and then filtering/pagination, with no filler. The inline format template is dense but earns its space; a slightly cleaner split between format and controls would help readability.

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

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

With no output schema, the description carries the burden of describing returns and does so convincingly (line format, stack trace, match count, cursor). For a nine-parameter tool it leaves the time-window params and the meta params (intent, llm_model) undiscussed, though the schema documents them.

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 it: it explains the `More:` cursor workflow for `after`, that logLevel/limit are applied server-side (not client-side truncation), and the shape of the output column layout. It says nothing about fromMs/toMs time-window semantics, though the schema covers those.

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 names a specific resource (the Jam's console output) and states the exact rendered format, so an agent knows this returns browser console messages rather than network events or video frames. It never explicitly contrasts itself with getEvents or getNetworkRequests, which is the only thing keeping it from a 5.

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: filtering with logLevel for problems and using `after` for paging tells the agent how to query, but there is no when-to-use/when-not guidance and no named alternative (e.g. getEvents or getNetworkRequests) for adjacent data needs. The agent must infer the boundary from sibling names 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?

Beyond the readOnly/idempotent annotations, it discloses the rendering convention (`[M:SS]` for pinned comments), what the json format adds (IDs, folder, event counts, processing status, 360p thumbnailUrl per pinned comment), and that it acts as a first-pass overview that points to other tools. It does not cover pagination/truncation limits on large Jam timelines, which keeps 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?

Front-loaded with the single most important fact (call it first) and the return summary, with format behavior positioned right after. The closing workflow sentences about createComment/submitFeedback/addResource are dense but partly choreography that belongs to those tools' definitions, making the tail heavier 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?

With no output schema, the description carries the return-value burden and does so thoroughly — text shape, json shape, and the `[M:SS]` annotation convention. For a read-only 4-parameter overview tool whose annotations already state the safety profile, 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 baseline is 3; the description earns a bump by explaining the consequence of `format: "json"` in terms of concrete payload contents (IDs, folder, event counts, thumbnailUrl) rather than repeating the schema's terse "structured payload a program parses". jamId and intent/llm_model semantics are left entirely 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 ("The entry point for any Jam") and enumerates the returned facets — title, description, author, page, browser/OS, comments, links, timeline — which unambiguously separates it from siblings like listJams, getEvents, or getMetadata. An agent can identify the tool's role 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?

Explicit ordering guidance ("call it first") plus follow-on routing to createComment, submitFeedback, addResource, and markRelated with the conditions that trigger each. It also names an exclusion: don't mention the creator if the creator is the user you act for.

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, closed-world), and the description adds real operational context: bodies are truncated at 4KB, JSON mode returns every stored column, and the first line carries the match count plus the UTC time of [0:00]. Pagination is only hinted at via the `More:` line reference rather than stated as a rule.

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 output shape before any filtering advice, and nearly every clause carries information an agent needs. Density tips into terseness in places — 'index for the events timeline lines name' is garbled enough to cost a re-read.

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 17 parameters and no output schema, the description carries the return-value burden and does so: it describes the text line format, the leading match-count/offset line, and the JSON alternative. A reader can call it correctly without opening the 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?

Adds semantics the schema cannot express: filters are arrays that OR within one and AND across, and 'a network or console filter implies its type', which explains the otherwise-ambiguous `types` default. It also clarifies body retention rules (failed requests always carry bodies; `bodies:'all'` cuts at 4KB; `headers:true`). Minor params (`after`, `limit`, `intent`) are 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: 'The Jam's recorded events as text, one line each', plus the exact line format `[M:SS #index]`. It does not distinguish itself from the three overlapping siblings (getConsoleLogs, getNetworkRequests, getUserEvents), leaving the agent to infer that this tool is the combined/filtered superset.

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 narrowing strategies — `index` for specific timeline lines, `fromMs`/`toMs` for a window around a moment, `types` for network/console/user — which tells the agent when each filter mode applies. It stops short of naming alternatives or when-not-to-use conditions relative to the type-specific siblings.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description goes further by disclosing the 30-frame cap and the Cloudflare Stream-only limitation, including how unsupported videos are reported.

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 front-loaded, dense, and free of filler. Every sentence adds either mode guidance, a limit, or a platform restriction.

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

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

Given the 10-parameter schema and no output schema, the description covers the key invocation constraints and return behavior well enough. It leaves intent and llm_model to the schema, which is reasonable since those are ancillary parameters.

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 documents every parameter. The description restates the mode and size semantics, adding only a small clarification that size does not apply to the overview.

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, 'Still frames from a video Jam, as images,' and its mode breakdown makes the output and scope immediately clear. It is easily distinguishable from siblings like analyzeVideo or getVideoTranscript.

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

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

It explicitly routes the agent to start with 'overview' and explains when to use 'at' versus 'window,' including the optional fromMs–toMs range. It adds a platform constraint, though it does not explicitly name sibling 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered without the description. The description usefully adds that the metadata originates from the app's own jam.metadata() SDK calls, which tells the agent about data provenance. It does not say what happens when no metadata was attached (empty object, null, error), which is the main behavioral 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?

A single short sentence with zero filler, and the identifying information (SDK-attached custom metadata) is front-loaded. It is a fragment rather than a complete sentence, which makes it slightly under-specified rather than bloated.

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

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

For a simple read-only, single-required-parameter tool with full schema coverage and no output schema, the description is close to sufficient but omits the return shape (key-value map? nested JSON?) — with no output schema present, that responsibility falls on the description. Adding one line about the response structure would make it complete.

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

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

Schema coverage is 100%, so jamId, intent, and llm_model are fully documented in the schema itself. The description adds no meaning beyond that — for example, it does not clarify accepted jamId forms or behavior for cross-workspace IDs. Baseline 3 is appropriate when the schema carries the parameter burden.

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 names the specific resource — custom metadata attached by the app via the jam.metadata() SDK — with concrete examples (user IDs, versions, feature flags). However, it is a noun-phrase fragment with no verb, so what the tool *does* (returns/reads this metadata for a jam) must be inferred from the name. It is distinguishable from siblings like getDetails or getEvents only by the resource examples, not by explicit contrast.

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?

There is no when-to-use guidance at all: nothing says when to pick this over getDetails, getEvents, or getUserEvents, and no prerequisites are stated. The mention of the SDK origin hints at the data's source but does not help an agent decide when to call it.

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

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

Annotations already certify readOnly/idempotent/non-destructive, yet the description still adds real behavioral detail: redaction of secret header values at capture, a 4KB cap on bodies, the default of bodies only for failed requests, and the `More:` pagination line referenced by the `after` param. Only response size/rate expectations are absent.

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 dense and front-loads the output format, which is right for a 15-param tool, but several clauses are garbled or run together, e.g. "`index` reads just the requests timeline lines name, with their bodies" and "with the error, bodies and headers under it", forcing the reader to re-parse rather than shortening.

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 supplies the return rendering, the byte costs, and the truncation/redaction rules, which is most of what a 15-param query tool needs. Gaps are minor: no guidance on handling large result sets beyond pagination, and no note on what an empty match looks like.

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 100% schema coverage the baseline is 3, but the description goes beyond it with semantics the schema does not encode: array filters are "OR within one and AND across", `index` pulls full bodies for specific timeline events, headers cost "about 600 bytes a request", and the first line carries the match count and UTC anchor for aligning with backend logs.

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 resource and output shape: "The Jam's network requests as text, one per line" plus an inline template. That clearly separates it from getConsoleLogs or getEvents, but the description never names a sibling, so an agent must infer the boundary itself.

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 through filter recipes — "statusCode (['4xx','5xx'] for failures)", "method ([...] for writes)", "filter first" before bodies:'all', and format:'json' "for digging into one event or window" — but there is no explicit statement of when to pick this tool over getEvents or getUserEvents, and no stated exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value the annotations cannot by enumerating the returned fields (name, type, target folder, expiration, jamsCreated), which matters because there is no output schema. It stops short of saying what happens when the publicId is unknown or expired.

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, zero filler, with the identity-and-scope statement front-loaded ahead of the return-value preview and the sibling pointer. Every clause carries information an agent would otherwise have to infer.

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 single-resource read with full schema coverage and a strong annotation set, the description covers purpose, return shape, and the natural follow-up tool. The only material omission is error behavior for a missing or expired publicId, which is light for a lookup tool.

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

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

Schema description coverage is 100%, including the intent and llm_model fields, so the heavy lifting is already done. The description only reinforces that publicId identifies which link to fetch, adding no format or lookup-source 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 ("Get a single recording link by its publicId") and the singular scope distinguishes it from siblings listRecordingLinks and listRecordingLinkJams. The second sentence previews exactly what comes back, so an agent knows what it is fetching 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?

The description routes the agent to listRecordingLinkJams for the follow-up paging case, which is explicit alternative guidance. It does not explicitly state the precondition that the publicId must come from listRecordingLinks, though "by its publicId" implies it strongly.

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 readOnlyHint/openWorldHint/idempotentHint annotations, it discloses the key behaviors: the call does NOT itself verify the domain, it returns a link a HUMAN must open in a browser with the extension live there, and the link expires in 5 minutes. That resolves the apparent tension between "Start verifying" and readOnlyHint=true, and the expiry detail is essential for correct retry logic.

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 the human-in-the-loop caveat and the polling follow-up; nearly every sentence carries routing or behavioral information. The expiry parenthetical is buried mid-sentence and a few phrases could tighten, but 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?

With no output schema, the description carries the return value itself ("Returns a verifyUrl") and explains the full lifecycle: human opens link, recorder confirms, domain marked verified, poll a sibling. Nothing needed 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 url, intent, and llm_model are already documented, and the hostname-matching note about url duplicates the schema text. The description adds no meaning for intent or llm_model (e.g., why they are required), 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?

"Start verifying a connected domain (recording URL)" gives a concrete verb and resource, and the description explicitly delimits it against siblings ("poll listRecordingUrls") and against the dashboard workflow. An agent can distinguish it from listRecordingUrls 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?

It states when to use it (connecting a domain so Jams capture console/network logs), names the alternative it replaces ("Use this instead of sending the user to the dashboard"), and gives the required follow-up (poll listRecordingUrls until verified: true). Exclusions and sequencing are 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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds one genuine behavioral fact beyond that: the tool returns nothing useful for video Jams. It says nothing about what the images look like on return (URLs, attachments, or binary) or what happens on an invalid jamId.

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, zero filler, with the content description front-loaded and the routing/exclusion rule second. Nothing could be removed without losing 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 simple three-parameter read tool with complete schema documentation and full annotations, the description covers what an agent needs to pick the right tool. The only residual gap is the return shape, which matters somewhat for an image-returning tool but is not required for correct invocation.

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

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

Schema description coverage is 100%, including the useful note that jamId accepts either a UUID or a jam.dev URL, so the baseline is 3. The description adds no parameter-level meaning beyond the schema and does not explain the intent/llm_model telemetry parameters.

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

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

States the resource precisely ("the images of a screenshot Jam") and explicitly separates it from the sibling that handles the other Jam type (getFrames for video). It's a noun phrase rather than a verb+resource formulation, so the agent must infer a fetch action, but the scope and content are 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 an explicit applicability rule ("Screenshot Jams only") plus the correct alternative for the excluded case (video Jam -> getFrames). It does not address overlap with other read tools like getDetails, getFrames-adjacent, or getMetadata, so routing among the broader read family 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 and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: the per-line `[M:SS #index]` format, inclusion of CSS selectors and coordinates, and the marking of script-fired clicks — output shape an agent could not infer from structured fields.

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

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

Front-loaded with the return payload, then the disambiguation. Two sentences, no filler. The clause about getDetails is slightly compressed but still 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?

With no output schema, the description compensates well by describing the returned text line format. It omits pagination behavior and the 200-event default, but those live in the schema, so nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so all eight parameters (including fromMs/toMs, limit, format and the `after` cursor) are already documented in the schema. The description adds only indirect hints — 'typed values' and 'positions' gesture at the content, but it explains nothing about time windows or pagination beyond what the schema says.

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 names the exact resource — the user's clicks, typing and navigations — and gives a concrete line format, so an agent knows precisely what comes back. It differentiates from the sibling getDetails by noting that timeline only summarizes these events, though it does not distinguish itself from getEvents.

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 supplies a direct routing rule: getDetails already lists the events, so call this one specifically for CSS selectors, click positions and typed values. That is explicit when-to-use-plus-alternative guidance; only an explicit exclusion case is missing.

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 safe, idempotent read, so the description is free to add the parts annotations cannot: the returned object shape, that chapters is null unless status is "ready", what "not_requested" and "skipped" mean, and that thumbnailUrl is a public 360p JPEG. That is unusually rich context about outcomes and failure states.

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 its return shape, and every clause is substantive. The telegraphic style (braced type literal, bare quoted status values before they are explained) makes it slightly harder to parse than plain prose, but nothing 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?

With no output schema, the description takes full responsibility for describing returns and does so completely: field list, nullability rule, thumbnail nature, downstream pointer, and status enumeration meanings. Nothing an agent needs to interpret the response 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 all three parameters (jamId, intent, llm_model) are documented there. The description adds no meaning about jamId format or the intent/llm_model obligation, so it sits at the baseline where the schema carries the parameter burden.

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 ("AI chapters of a video Jam") and immediately distinguishes itself by declaring the exact return shape and by routing visual inspection to getFrames. An agent can tell it apart from getVideoTranscript or analyzeVideo 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 clear routing guidance for the visual case ("to look yourself, call getFrames with mode 'at' at the chapter's midpoint") and explains why output may be empty via the status semantics. It does not explicitly contrast with getVideoTranscript or analyzeVideo, which are the closest text/media siblings.

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds meaningful context beyond that: the transcript only exists for Video Jams recorded with the microphone on, which tells the agent when the tool will return nothing useful.

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 output format and followed by the availability constraint and the sibling overlap. Every sentence contributes a distinct fact and none 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 correctly states the return format (WebVTT with timestamps) and the precondition for a non-empty result. For a simple single-resource read tool, that is close to complete, with only an explicit pointer to getDetails as an alternative 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 jamId, intent, and llm_model are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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 names the resource precisely — speech captured while recording, returned as WebVTT with timestamps — which no sibling name conveys on its own. It is a clear statement of what this tool yields, though the verb is implicit rather than stated outright.

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 implicitly routes the agent away from unnecessary calls by noting that the getDetails timeline already carries this content as `Voiceover:` lines. That is a real usage signal, but it stops short of an explicit 'use this when you need X instead of getDetails' instruction.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds value beyond that by disclosing the return payload (name, short ID, Jam count, timestamps) and confirming that search and pagination are optional, which an agent needs in order to interpret results.

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 core action, followed by return contents and then the use case. No filler or redundancy; the only minor inefficiency is that the return-fields sentence partially duplicates what an agent would infer from a list operation.

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, zero-required-parameter list tool with full schema coverage and rich annotations, the description covers purpose, scope, and returned fields. The only gap is pagination mechanics — it does not say how an agent detects that more pages exist or that results are cursor-based beyond the 'after' parameter.

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%, with every parameter documented in the schema including the after-cursor, limit bounds, query, orderBy enum, and the intent/llm_model fields. The description only restates that search and pagination exist, adding no format, default, or cursor-chaining 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?

The description gives a specific verb and resource ("List folders in the team") plus the scope of optional filtering and pagination, so the operation is unambiguous. It does not explicitly name a sibling to contrast with (e.g., searchJams or listJams), but the stated use case of discovering folders for organizing Jams effectively separates it from the Jam-listing 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?

"Use this to discover available folders for organizing Jams" supplies a positive use context, which is more than nothing. However, it never states when not to use it or points to alternatives such as searchJams for content lookup, and there is no mention of prerequisites like team membership.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by describing returned Jam metadata and the special handling of each Jam's url as a share link to return unchanged.

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 sentences, front-loads the deprecation warning, and then efficiently covers filters, return values, and the special url handling. There is no unnecessary wording.

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 read-only listing tool with no output schema, the description provides enough context: it names the filter dimensions, mentions pagination, and describes the returned metadata and share-link behavior. The schema covers parameter details, so the remaining gap is minor.

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 input schema already documents all 12 parameters in detail. The description summarizes the filter categories and pagination but does not add syntax or format details beyond what the schema provides, making the baseline score 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: it lists Jam bug reports using legacy filters and pagination. It also explicitly names the sibling replacement, searchJams, so an agent can distinguish this deprecated tool from the current 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?

The first sentence gives explicit when-not-to-use guidance: 'Deprecated: use searchJams instead.' This directly routes the agent to the correct alternative and makes the legacy status 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, closed-world), so the description's job is to add what they cannot. It does that by declaring the return shape ('name, email, and role') and flagging that search and pagination are optional. It omits default page size, cursor semantics, and empty-result behavior, which are left to 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?

Three short sentences, front-loaded with what the tool does, then the return value, then the use case. Nothing is redundant and nothing is padded.

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?

All parameters are optional and fully described in the schema, and with no output schema the description usefully names the returned fields. The main remaining gap is the absence of pagination traversal behavior, but for a simple read-only list that is minor.

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 each of the five parameters documented in the schema itself, so the baseline is 3. The description's 'optional search and pagination' adds a small framing hint but no format or constraint details beyond what the schema already says.

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 team members') plus the modifiers (optional search and pagination), and adds the returned fields. No sibling tool lists members, and the 'team members' phrasing is unambiguous against search/searchJams.

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 concrete use case ('find users for filtering Jams by author'), which tells the agent when this call is warranted. It stops short of naming an alternative or an exclusion ('use X instead when...'), so it is clear context without routing rules.

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 behavior beyond that: the returned fields (id, title, createdAt), newest-first ordering, and the cursor/hasNextPage pagination contract — meaningful 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 tightly packed sentences with zero filler — purpose, then return shape and ordering, then pagination mechanics. Front-loaded with the core purpose before the procedural detail.

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

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

No output schema exists, so the description must convey the return shape, and it does (id, title, createdAt, newest-first, cursor/hasNextPage). Combined with full schema coverage and read-only annotations, an agent has everything needed to invoke and iterate pages 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 all five parameters are already documented. The description's cursor explanation ("a jam id from a prior endCursor") nearly restates the schema text and it adds nothing about limit, intent, or llm_model; the mention of hasNextPage is a return field, not a 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 opens with a specific verb+resource ("List the Jams recorded through a recording link") and states the addressing key (publicId). That scope phrase distinguishes it from listJams (all Jams) and getRecordingLink (the link itself) without the reader needing to open any schema.

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

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

It clearly says how to page: pass cursor from a prior endCursor and check hasNextPage. It doesn't explicitly say when to prefer this over listJams or when to call getRecordingLink first, so there is no exclusion/alternative routing, but the calling 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds real behavior: default ordering (newest first), cursor pagination semantics, the presence of `hasNextPage`, and the default exclusion of revoked links, though it says nothing about team-scoping/authorization 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?

Four short sentences, front-loaded with what is listed and the ordering, then returns, then pagination, then the revoked filter. Every sentence carries information an agent would otherwise have to guess.

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, and the description compensates by naming the returned fields (publicId, name, type) and the pagination flag hasNextPage. Combined with annotations and full schema coverage, an agent has everything needed to call this correctly for a simple 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?

Schema description coverage is 100%, so `limit`, `cursor`, and `includeRevoked` are already documented in the schema with defaults and bounds. The description restates the same cursor and revoked-behavior semantics rather than adding new detail, so the baseline 3 applies despite its clarity.

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 names a specific verb and resource ('List the team's recording links') plus ordering ('newest first') and pagination model, and it distinguishes the tool from getRecordingLink (single fetch) and listRecordingLinkJams by making clear this returns links with publicId, name, and type.

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 concrete usage conditions for pagination ('Pass `cursor` ... to fetch the next page') and for the revoked-link case ('unless `includeRevoked` is true'), which is explicit when-to-use guidance. It does not explicitly exclude any sibling, e.g. it never says to use getRecordingLink when you already have a publicId.

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, closed-world), so this adds domain-specific behavior instead of repeating it: unverified domains silently capture no logs, verification happens outside the API in the dashboard, and an empty list means any link created now captures nothing. Those are exactly the failure modes an agent needs to know before proceeding.

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

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

Front-loaded with the purpose, then the return shape, then routing guidance, then the verification caveat — a sensible order. Slight redundancy between "to tell whether the team has any connected domains at all" and the closing sentence about an empty list, which costs a perfect score.

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 enumerates the returned fields (id, url, verified state) and explains the empty-list case, which is the main branch an agent must handle. For a zero-required-parameter read tool, 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?

Both parameters (intent, llm_model) have full schema descriptions, so the schema carries the burden and baseline 3 applies. The description adds no extra meaning about these parameters, but none is needed since they are generic telemetry fields unrelated to the tool's domain logic.

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 team's connected domains (recording URLs)") and immediately disambiguates what a recording URL is: the domain a recording link starts from so Jams capture console and network logs. That definition distinguishes it from sibling link-management tools like createRecordingLink and getRecordingUrlVerifyLink without needing to open any schema.

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

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

Explicitly says to call this before createRecordingLink to pick the recordingUrlId, and to use it to determine whether the team has any connected domains at all. It also states a prerequisite condition — only a verified domain captures logs, and an unverified one must first be verified from the dashboard, with a doc link.

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

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

The description adds substantial behavior beyond the annotations: both Jams display the link, the target shows an inverse label, re-marking with the same type is a no-op, it returns the relation, and it requires a permission level that ranks with editing a Jam's title. However, the idempotency claim substantially overlaps idempotentHint and the destructiveHint=false write behavior is only implied, so the incremental value is solid but not exceptional.

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 purpose clause followed by type semantics, side effects, usage examples, and permission requirements - every sentence contributes. Some sentences are long and pack multiple facts, but 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?

Covers the enum behavior, side effects on both Jams, idempotency, permission prerequisite, and return value, so an agent has what it needs to call it correctly despite no output schema. Only the absence of explicit guidance for the reverse operation (markUnrelated) leaves a small 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 100%, so the baseline is 3, but the description adds real meaning: it explains what fixes, proves, and relates_to actually signify and confirms both Jams must belong to the same team. The intent and llm_model params remain unexplained, which is fine given their 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?

States a specific verb and resource ('Mark a Jam as related to another Jam of the same team') and then defines the three relation types, their meanings, and the default. An agent can distinguish this from markUnrelated or updateJam from the description alone.

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 when-to-use guidance: record a Jam that proves a fix, or connect a set of Jams covering one flow such as one Jam per UI state. It does not explicitly name markUnrelated as the alternative for disconnecting, so routing guidance 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine scope beyond that: the removal is unconditional across every relation type and additionally strips the target Jam's backlink, which tells the agent exactly what state is destroyed.

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 short sentences, zero filler, with the destructive scope front-loaded. Nothing here repeats the name or title redundantly.

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 relation-clearing tool with no output schema, the description covers the important part — that all relation types and backlinks are removed — and annotations supply the safety hints. It stops short of noting error behavior when no relation exists or pointing at markRelated as the undo-side counterpart.

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 jamId, targetJamId, intent, and llm_model are already documented, including that identifiers may be UUIDs or jam.dev URLs. The description adds no parameter-level detail, which meets the baseline when the schema carries the full burden.

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 specific verb and resource: remove every relation from one Jam to another, and states the scope is type-agnostic. It does not name the sibling markRelated, so the agent must infer the inverse operation from the name alone.

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 by the verb 'Remove' — the agent can conclude this is the tool for severing a link, but the description never states when to prefer it over markRelated, nor does it say what happens if the two Jams were never related.

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; the description adds real context on top — that only the caller's own reaction is removed, that others' identical-emoji reactions survive, that a missing reaction is a no-op, and that the change propagates to public viewers. It does not describe the response body or what happens on an invalid commentId, which keeps it below 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 core behavior and ownership constraint are front-loaded in the first two sentences, with edge cases and visibility following. The emoji enumeration duplicates the schema enum descriptions and is the one sentence that does not fully earn 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 4-parameter mutation with no output schema, the description covers ownership scoping, idempotency, valid inputs, and visibility of the effect — enough to call it correctly. It omits any indication of the success/failure response shape, which is the only material gap given annotations already handle the safety profile.

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 required parameters (commentId, emoji) are fully documented in the schema. The description's emoji list merely restates the enum descriptions verbatim and adds nothing about commentId resolution or the intent/llm_model fields. Baseline 3 applies when the schema carries the 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+resource ('Take back a reaction you left on a comment'), making it immediately distinguishable from the sibling addReaction. Scope is narrowed to the caller's own reaction, so an agent knows exactly what this operates on.

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 implicit but strongly cued: 'Take back a reaction you left' plus the no-op note tell the agent this is the inverse of adding and is safe to call speculatively. It never names addReaction as the alternative for the opposite action, so it stops short of explicit sibling 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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered structurally. The description adds a genuinely useful behavioral fact — matching is exact-string against the previously added URL — but says nothing about what happens on a non-matching URL, whether removal is silent or an error, or whether other resources are affected.

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 short sentences, action first and constraint second, with no redundant restatement of the name or annotations. Every sentence 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 destructive mutation, the annotations carry most of the weight (destructive, idempotent, open-world), and the description correctly emphasizes the exact-match requirement, which is the main way an agent can fail here. The remaining gap — the failure/return behavior when the URL is absent — is minor given idempotentHint=true.

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 are already documented, and intent/llm_model are self-explanatory. The 'exactly as it was added' clause adds real meaning beyond the schema's loose 'http or https URL' phrasing by implying exact-match semantics, but it addresses only one parameter, 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?

The description states a specific verb and resource ('Remove a URL from a Jam's resources'), which is unambiguous and naturally pairs off against the sibling addResource. It stops short of explicitly naming the inverse operation, but the verb alone makes the distinction clear.

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?

There is no when-to-use guidance: nothing says when to remove a resource versus deleting the whole Jam, nor what prerequisites (permissions, membership) apply. The only guidance offered, 'Pass the URL exactly as it was added,' is a parameter constraint rather than a usage condition.

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, closed-world), so the description's added value is the cardinality guarantee of 'at most one result' and the team-scoped lookup, which help an agent reason about the response. It does not say what happens when nothing matches (empty result vs. error), leaving a small behavioral 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?

Two dense sentences: the capability and cardinality come first, the routing hint second. Nothing is repeated and no words are 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 three-parameter read-only lookup with a fully documented schema and complete annotations, the description covers purpose, scope, cardinality, and the alternative. The only omission is not-found behavior, which is minor given the low 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 the query parameter already documents that it must contain a UUID or jam.dev URL. The description mirrors that constraint but adds no format, syntax, or validation 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?

The description gives a specific verb and resource — 'Resolve a video Jam ... from a UUID or jam.dev URL' — and immediately bounds the outcome ('at most one result'). It also explicitly disambiguates from the nearest sibling by declaring 'No title search: use searchJams', which is critical given the tool's generic name 'search'.

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 positive case (query holds a UUID or jam.dev URL), the negative case (title search), and the alternative that handles the negative case (searchJams). The 'in the connected team' phrasing also scopes where lookups apply, so an agent has both when-to-use and when-not without 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 establish readOnly/idempotent/non-destructive, and the description adds genuinely non-schema behavior: the team is fixed by the issued token and 'no argument can name another', and each returned Jam carries a `url` share link to hand back unchanged — the latter is important given there is no output schema. It still omits result-shape detail beyond the url and any rate-limit/large-result 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?

The scope and team statements are front-loaded and earn their place, but the long single-clause sentence reproducing the short-term comment-matching rule duplicates the `text` schema text almost verbatim and crowds out what an agent actually needs (routing versus siblings).

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 10-parameter, nested, unannotated-output search tool, the description never addresses the two auxiliary parameters `intent` and `llm_model`, nor result size/pagination behavior beyond 'opaque cursor the previous page returned'. Most consequentially, with `search` and `listJams` as siblings, the missing differentiation leaves the agent without enough to call the right tool.

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

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

Schema description coverage is 100%, so `text`, `textIn`, `where`, `window`, `sort`, `page` and `options` are already fully documented. The description largely re-narrates those same clauses rather than adding new meaning; it adds only the framing that all `where` leaves are ANDed and a pointer that the schema lists each field and operator.

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 and scope: 'Search the connected team's Jams', and the closing sentence clarifies the search cover surfaces (title, description, comments, linked issues, reporter, transcript). It never names the obvious siblings `search` or `listJams`, so an agent cannot tell from this text alone which of the three to pick.

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

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

No when-to-use guidance at all: nothing says when to prefer this over `listJams` (browse without query) or `search` (the other search tool in the sibling list). The only guidance-like content is the token-scoped team constraint, which is a restriction rather than a selection 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 well beyond the annotations: it discloses that no human reads the report and no approval is needed, that oversized bodies are rejected without saving or truncating, the word/character ceilings, and the prohibition on secrets, customer data, source code, and stack traces. These are operational facts an agent cannot infer from readOnlyHint=false / destructiveHint=false alone.

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

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

Front-loaded with purpose and return value, then routing rules, then limits. It is dense but almost every clause changes agent behavior; the only real redundancy is restating the 2000-word/100,000-character ceiling already present in the `body` schema description.

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 mutation with no output schema, the description covers what is written, what is returned, who consumes it, when to send it, and how often — enough to call it correctly on the first attempt without further context.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining the jamId + evidence pairing for cause reports and the ordering rule for `evidence` ("first the source without which you would not have found the cause"). It does not further explain `intent`, `category`, or `llm_model`, which the schema already covers.

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: "Save feedback about a Jam surface in Jam's database for Jam's agents to read," plus the return value (stored feedback ID and a thank-you). No sibling tool covers feedback submission, and the description makes the tool's distinctive role unmistakable.

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

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

Explicit when-to-use (tool/CLI/doc/skill was wrong, stale, confusing, missing — or worked unusually well; or you found a Jam's root cause), explicit when-not (not another MCP server's tools, not the user's own skills/scripts, not the user's product, not slips you corrected yourself), and explicit rate limits (one problem report per session plus one evidence report per Jam).

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 destructive, idempotent, non-open-world, non-read-only. The description adds genuinely new behavior: three ways to identify the target folder and the not-found semantics for unknown or cross-team folders. It does not explain why the operation is flagged destructive or whether the old name is recoverable, so a small gap remains.

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

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

Three short sentences, front-loaded with the action and then the sibling exclusion and error semantics; nothing is wasted. The folder-identification sentence slightly duplicates the schema, keeping it from a perfect score.

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 rename tool with full schema coverage and rich annotations, the description supplies the missing pieces an agent needs: target resolution options, sibling routing, and failure behavior. Return-value detail is not needed since there is no output schema and the operation is a straightforward mutation.

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 required parameters and the intent/llm_model fields are already documented inline. The description's mention of name/ID/short-ID lookup largely restates the folder parameter's own schema text and adds no format or resolution-order detail (e.g. precedence when a name collides with an ID).

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

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

"Rename a folder" gives a specific verb and resource, and the follow-up sentence explicitly narrows the scope ("Renaming does not move any Jams") so an agent cannot confuse it with updateJam. It is clearly distinguishable from createFolder/deleteFolder/listFolders siblings.

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

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

The description explicitly routes the adjacent operation elsewhere ("use updateJam for that"), which is the main confusion risk among siblings. It does not spell out when not to call it (e.g. permissions or a folder-name conflict path), so it falls 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is structured. The description adds genuine context: partial-update semantics (only passed fields change) and the Admin/Creator role requirement for title and description edits. However, it never addresses the destructiveHint — that rewriting a description overwrites prior content — nor what the call returns.

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 capability then the partial-update rule then the permission caveat. No filler. The folder-resolution sentence is verbatim schema duplication and could be cut without loss.

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

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

For a mutation tool with six parameters, no output schema, and rich annotations, this covers the essentials: what can change, that changes are partial, and who is allowed. The omission of return shape is acceptable given no output schema, but the unexplained destructiveHint leaves a small 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 the description is held to the baseline, but it largely restates schema text (the folder name/ID/short ID/"root" resolution is copied from the parameter description). It adds nothing about jamId accepting a UUID or jam.dev URL, and says nothing about intent or llm_model. At best it reinforces a single parameter.

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 names a specific verb and resource ("Update a Jam bug report") and enumerates the three operations it supports: rename, rewrite description, move between folders. An agent can immediately distinguish it from deleteJam, updateFolder, and listJams without consulting 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?

It makes the usage model explicit: every field is optional, only passed fields change, and folder accepts a name/ID/short ID/"root". It also states the role prerequisite for title/description edits. It stops short of naming alternatives (e.g. that folder management itself belongs to updateFolder/createFolder) or stating when not to use it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond them with partial-update semantics, two failure modes (not-found for unknown/other-team, revoked links uneditable), and a non-obvious side-effect clarification that 'Existing Jams are not moved' when the folder changes. It still says nothing about authorization requirements or whether metadata replacement is recoverable, which matters for a destructive call.

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 identifying verb and resource, then fields, then constraints and edge cases in short declarative sentences. Every sentence carries distinct information; nothing is restated from the schema verbatim beyond the field list needed to frame usage.

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 9-parameter mutation with no output schema, the description covers the semantics and failure modes well but omits what the call returns and what permissions are needed. An agent knows when to call it and what gets changed, but not what comes back or what auth level is required.

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 real meaning beyond the schema: the folder parameter is scoped to 'future recordings' and explicitly does not relocate existing Jams, and metadata is framed as a full replacement. The intent/llm_model bookkeeping parameters are not mentioned, which keeps it from a 5.

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

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

Opens with a specific verb+resource+identifier: 'Update a recording link by its publicId,' then enumerates exactly which fields can be modified (name, folder, Jam title, reference, expiration, metadata). This distinguishes it from createRecordingLink, getRecordingLink and deleteRecordingLink by verb alone, though no sibling is named 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?

The 'Use it to...' clause gives concrete use cases and the partial-update rule ('Only the fields you pass are changed') tells an agent it needn't send the full record. Failure conditions ('Unknown or other-team links return not-found; revoked links cannot be edited') are stated, but no explicit routing to getRecordingLink for reads or createRecordingLink for new links.

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