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

The description discloses the crucial non-obvious behavior: messages are marked as read, which explains why readOnlyHint=false and idempotentHint=false despite this looking like a fetch. It doesn't cover blocking behavior, rate limits, or whether all messages or only unseen ones come back.

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 no padding, and the read-marking side effect is placed where it is immediately visible. The phrasing 'Take new messages... sent to this live session' is slightly convoluted but not wasteful.

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

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

With no parameters and no output schema, the agent still has no idea what comes back (a list of messages? an empty result when none?) or whether the call waits for new messages. For a polling-inbox tool that is a meaningful gap, though the critical read-marking behavior is covered.

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

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

Zero parameters, so there is nothing for the description to document; the baseline for a parameterless tool applies. No parameter semantics gap exists.

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 resource and scope are specific: new messages from teammates addressed to this live session. The verb 'take' is a little ambiguous (retrieve vs. consume), but the parenthetical clarifies the side effect and sets it apart from send_live_message.

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

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

No guidance on when to call this versus siblings like live_status or team_activity, and no statement of polling cadence or preconditions (e.g., must start_live have been called first). The agent must infer the call context entirely.

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

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

Annotations already declare the write/append shape (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds a genuine unstated constraint: "Never include secrets," which matters precisely because the note is team-visible. It does not disclose that repeated calls create separate additive notes (idempotentHint=false) or that notes cannot be edited or removed, which would complete the picture.

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 front-loaded sentence names the action, the audience, and the accepted content types, closing with the safety caveat. Nothing is redundant and nothing needs to be 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?

For a simple two-parameter tool with full schema coverage and annotations covering the safety profile, the description supplies purpose, audience, and content constraints, so an agent can call it correctly. What is missing is edge behavior — whether the session must already be shared, and what happens on failure — though with no output schema this is a minor gap.

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

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

Schema coverage is 100%, so both `id` and `body` (with minLength/maxLength and plain-text-or-Markdown guidance) are fully documented structurally. The description adds only the "short note" framing and the no-secrets content rule for `body`, which is a modest increment over 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 ("leave a short note on a shared session") and enumerates the note types (question, finding, picked-it-up), which clearly separates it from update_session or share_current_session. It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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 examples given ("a question, a finding, or that you picked it up") communicate when an agent should reach for this tool rather than mutating the session. There are no explicit exclusions or named alternatives, so a borderline case like "I want to change session metadata" has to be 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real value on top by disclosing default behavior ('tail' is default), the payload shape, and that 'full' is paged via offset. It does not state sharing/permission prerequisites or any size limits for retrieving a shared session, which would have pushed this higher.

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?

Very compact: one sentence naming the payload followed by a terse mode legend, with the default mode stated up front. It is dense but every clause carries information; a slightly cleaner breakdown of mode-to-parameter pairing would earn a 5.

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

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

With no output schema, the description does the necessary work of naming returned content and explaining paging, which is enough for an agent to call it correctly. Missing pieces are minor: where the id comes from is only in the schema, and there is no mention of permission or sharing requirements for open-world session access.

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 semantic meaning beyond the schema: it clarifies the interplay of mode with offset ('full' = full transcript, paged with offset) rather than merely restating the enum values. The 'tail' integer parameter's interaction with mode is only implied, not spelled out in the description.

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

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

States a specific verb and resource ('Load a shared session') and enumerates the payload an agent gets back: summary, decisions, next steps, files and conversation. It does not explicitly differentiate itself from the similarly-named sibling get_session_diff or point to list_sessions/search_sessions for id discovery, so sibling routing is left to inference.

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

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

Explains the three modes and their trade-offs clearly — 'tail' (default) for summary plus recent messages, 'summary' for summary only, 'full' for the complete transcript with offset paging. What is missing is guidance on when to prefer a sibling such as get_session_diff or when to fall back to search_sessions instead of loading.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds genuinely new context: the diff is uncommitted work authored by a teammate, it is a unified diff, and it is not applied by this tool. It does not describe truncation behavior, though max_chars in the schema covers that.

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 with no filler; the core deliverable is stated first and the operational follow-up second. Every clause carries information.

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

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

With no output schema, the description carries the return-value burden and does so by naming the format (unified diff). Minor gaps remain: behavior on a session with no attached changes, or on a missing/unauthorized session id, is not stated.

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 `id` and `max_chars` (with range and default) are already documented in structured data. The description adds no syntax or format detail about either parameter, so baseline 3 applies.

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

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

States precisely what is returned: the uncommitted changes attached to a shared session, in unified diff format. This is a specific resource plus an explicit output format, and it clearly separates the tool from siblings like get_session (metadata) and list_sessions.

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

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

"Use it to see exact code state" gives a positive selection criterion, and the follow-up tells the agent exactly what to do with the result (write to file, `git apply`). It stops short of naming an alternative sibling or stating when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds a real behavioral fact the annotations don't carry: results are silently filtered to the current repo unless all_repos is set. That default-scoping disclosure is the kind of context an agent needs to avoid missing data.

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

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

Three short sentences, no repetition. The core purpose and the important default-scope caveat come first, with the for_me exception last. 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?

For a read-only, fully documented list tool with annotations and no output schema, this covers the essentials: scope default, escaping the default, and the for_me exception. It could still say what ordering/pagination look like or point to search_sessions for filtered lookups, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already explains all seven parameters and their defaults; baseline is 3. The one genuine addition is that for_me pulls handoffs 'from any repo', clarifying how that flag interacts with the default repo scope — but the remaining parameters get no extra description-level meaning.

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

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

Opens with a specific verb and resource: 'List sessions teammates have shared.' The shared/teammate framing and repo scoping help separate it from generic listing siblings, but it never names search_sessions or get_session, so the boundary with those siblings is left implicit.

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 scoping rules (default current repo, all_repos for everything, for_me for handoffs), which is useful context, but it never states when to prefer this over search_sessions or get_session. The agent must infer the alternative from the sibling name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds genuine value by enumerating exactly what the payload reports, including the live-vs-stale distinction. It stops short of noting permission/scope limits (whose sessions are visible) or freshness/caching behavior, which matters for a presence 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?

A single sentence with zero filler, front-loaded with the core framing and then listing the returned fields in the order an agent would evaluate them. Nothing is repeated from 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?

With no parameters and no output schema, the description carries the return-value burden and does so by naming every reported field, which is sufficient for an agent to judge relevance. The only gap is scope: it never says whose activity is returned (own team, org, or open world).

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

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

Zero parameters, so the baseline of 4 applies and there is no parameter semantics burden to satisfy. The description correctly implies the call takes no arguments by framing it as an ambient status read.

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?

Clearly states the resource and intent: current live presence plus a concrete inventory of what the response contains (repo, branch, activity, recent files, live flag). It does not, however, distinguish itself from close siblings like list_sessions, team_activity, or get_session, so an agent must infer which 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?

The phrase 'right now' implicitly scopes this to real-time presence checks rather than historical session queries, which weakly separates it from list_sessions and get_session. There is no explicit when-to-use guidance, no named alternatives, and no statement of preconditions (e.g., whether a live session must exist).

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds which fields are searched and the inline filter syntax, but says nothing about result ordering, ranking, result caps, or whether filters must appear in the query string versus using the separate author/this_repo_only parameters.

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

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

Two front-loaded sentences with no filler: the first defines scope, the second supplies the non-obvious query syntax. Nothing to trim.

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 should hint at what a result looks like and how matches are ordered or limited; it omits both. Adequate to invoke the tool, but leaves an agent guessing about result shape and the interaction between query filters and the author/this_repo_only 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 baseline is 3; the description earns a point by documenting the 'file:<path>' and 'branch:<name>' query-filter syntax, which goes beyond the schema's single example string and clarifies in-query filtering behavior.

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 (full-text search over shared sessions) and names the searched fields (titles, summaries, messages). It is clearly distinguishable from get_session or share_current_session, though it never contrasts itself with the closest sibling list_sessions.

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

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

Usage is implied by 'full-text search' versus a listing tool, and the filter syntax hints at narrowing behavior. There is no explicit statement of when to prefer this over list_sessions or how to combine author/this_repo_only with the inline filters.

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 behavioral context beyond the annotations: delivery is interleaved with the teammate's work ('between steps'), so it's a live, non-durable channel, and there is an explicit safety constraint against secrets. Open-world and non-idempotent hints are consistent with sending to people, but the description doesn't say what happens if no live session 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 short sentences, front-loaded with the action and delivery mechanism, then purpose, then the safety rule. No filler or repetition.

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

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

Given a fully documented schema and no output schema, the description supplies the missing conceptual context: who receives it, when it lands, and the secrets prohibition. Gaps remain around failure modes (no live teammate, message length limits) and whether a response is returned.

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 every parameter (to, kind, reply_to, wait_seconds) is documented in the schema itself. The description only reinforces brevity ('short message') and the secret prohibition, adding little parameter-level meaning. 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 (send a short message) plus the delivery target: a teammate's live agent, reaching them between steps. That distinguishes it from a durable comment or inbox check, though it never names the sibling it differs from (e.g. comment_on_session, check_live_inbox).

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 contexts: flag a change that affects them, ask a question, answer theirs — plus a clear safety rule ('Never include secrets'). It stops short of explicit exclusions or naming alternative tools for durable/asynchronous communication.

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 disclose the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds genuinely useful context that the output is published and consumed by teammates, plus a secrets-hygiene warning, but it omits the non-idempotent consequence (each call creates a new share) and the visibility/permission implications that openWorldHint implies.

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, zero preamble, and the single most consequential instruction (author the summary yourself) is front-loaded right after the purpose statement. Nothing is redundant with the schema.

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 14-parameter publishing tool with no output schema, the description says nothing about what comes back (a session id, a link to paste, a confirmation) or what happens to the transcript once shared, which the agent needs to close the loop. The anthropomorphic framing and secrets warning carry it to adequate, but not 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% across 14 parameters, so the schema already documents goal/done/next/include/continues/pr_url defaults and the enum. The description adds no parameter-level detail beyond gesturing at "the summary" as a whole; with the schema doing all the work, 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?

"Share the session you are in right now with the team" gives a specific verb (share), an unambiguous resource (the current session, not an arbitrary id), and the audience. It implicitly separates itself from get_session/list_sessions reads, but it never names a sibling (e.g. share_template, update_session) the way it could.

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

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

The description tells the agent how to approach the call (author the summary yourself, since it is read first) and gives one hard constraint (never include secrets). It says nothing about when this is the right tool versus share_template, update_session, or comment_on_session, so the alternative selection 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the template may include required sections and instructions the agent must follow, which is genuinely useful behavioral context, but it is silent on failure modes (no repo, no template) and on whether the result should be re-read per session.

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, no filler, with the resource definition first and the sequencing instruction second. Every clause carries information an agent needs.

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 parameters and no output schema, the description's job is to convey what comes back, and it does: extra sections, some required, plus sharing instructions. Only the edge cases (missing template, non-repo context) are unaddressed, which is minor for a zero-arg 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?

Zero parameters and 100% schema coverage, so there is nothing for the description to disambiguate. Baseline 4 applies; the description's note that the template is scoped to 'the current repo' implicitly explains why no repo argument exists.

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 resource and scope: 'The handoff template for the current repo', plus what it contains (extra sections, some required, and sharing instructions). The name 'share_template' sounds like a write/sharing action, and the description corrects that, though it never uses a retrieval verb like 'returns' or 'fetches' so the read nature is only implied.

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?

'Call it before share_current_session' gives explicit sequencing guidance and names the relevant sibling. It stops short of saying when not to call it, whether a repo context is required, or what to do if no template exists.

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

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

Beyond the annotations, the description discloses real consequences the annotations cannot express: teammates see what you're working on and which files you touch, and their messages are injected between steps. That is meaningful disclosure of side effects and social visibility. It is consistent with readOnlyHint=false, idempotentHint=true 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?

Two compact sentences with the core action front-loaded and no filler. The final clause about listing who else is live is secondary information that could arguably live in a return-value note, but it is not wasteful.

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

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

For an all-optional, two-parameter state-changing tool, the description covers the effect on teammates and hints at the return content ('lists who else is live'). With no output schema and no annotations explaining output, the response shape is only partially covered, which keeps this short of a 5.

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 'title' and 'autonomy' are already documented in the schema, including the important caveat about only setting autonomy=true when explicitly requested. The description adds nothing about either parameter, so the schema-carries-it baseline of 3 applies.

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

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

States a specific verb and resource ('Start working live in this repo') and describes the resulting state change — activity visible to teammates and messages delivered between steps. It is clearly distinct from stop_live/update_live, though the trailing 'Lists who else is live here' blurs it slightly with live_status.

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

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

Usage is implied: this is the entry point for going into a live session in a repo. However, there is no explicit when-to-use/when-not, no mention of prerequisites, and no routing to the near-duplicate sibling live_status for reading peer state.

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 (idempotent, non-destructive, open-world), so the description's job is to add effect detail — and it does: teammates stop seeing the session and messages stop arriving. It does not say whether the live session can be resumed or what happens to already-sent messages, but the core observable effects are disclosed.

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

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

A single sentence with the action front-loaded and two concrete consequences appended; nothing is wasted and nothing critical is buried.

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

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

With no parameters, no output schema, and annotations carrying the safety profile, the description covers what an agent needs to invoke it correctly. The one gap is recoverability — whether the live session can be restarted — which would help an agent decide before ending it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 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 ('End') and resource ('this session's live session'), making the action unambiguous. It is distinguishable from start_live by the 'End' verb, though it never names the sibling 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 scope word 'this session's' implies when the tool applies, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as start_live for restarting or live_status for checking state. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful scope cues — results are personalized ('handoffs for you') and grouped by repo — but says nothing about result limits, ordering, or whether the aggregation spans workspaces.

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, front-loaded with the core concept and then the content categories. Slightly list-like and fragmentary, 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?

For a read-only feed with no output schema, the description usefully previews the returned content categories. It still omits things an agent would want — ordering, pagination or truncation, and how 'for you' is determined — which leaves it merely adequate.

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

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

Schema coverage is 100% and the single 'days' parameter is fully documented in the schema (1-30, default 1). The description's 'recently' loosely reinforces the lookback window but adds no format, timezone, or boundary semantics beyond 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 enumerates the concrete content of the feed (new shares by repo, handoffs, pickups, comments), which lets an agent tell it apart from the session-centric siblings like list_sessions or search_sessions. It stops short of a clean verb+resource statement ('What the team did recently' is a noun phrase), but the intent is unambiguous.

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

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

There is no guidance on when to call this versus list_sessions, search_sessions, or get_session, and no exclusions or prerequisites. The agent must infer that this is a cross-repo digest feed rather than a per-session lookup.

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

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

Annotations already declare non-readonly, idempotent, non-destructive, open-world. The description adds genuinely new context: changes are visible to teammates, and the autonomy flag has a consent precondition ('true only if the user explicitly asked'). It doesn't say whether omitted fields are left unchanged, though idempotentHint implies replacement semantics.

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

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

A single sentence, front-loaded with the verb and the affected surface. The trailing 'or whether this agent may act...' clause is slightly convoluted but earns its place by covering the third parameter group.

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 full schema coverage and annotations covering the safety profile, the description covers what the agent needs to call it. The notable remaining gap is disambiguation from the 'update_session' sibling, which would materially help selection.

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

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

Schema coverage is 100%, so all three parameters are already documented and the autonomy constraint is largely restated from the schema. The description adds only the framing that title/status are teammate-visible, which is useful but thin.

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 ('Change') and resource ('this live session') and names the two field groups affected (teammate-visible info, and act-on-messages permission). It does not distinguish this from the sibling 'update_session', leaving ambiguity between two similarly named update 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?

Usage is implied by 'what teammates see' but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. update_session vs update_live). The agent must infer the choice from the name alone.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description supplies the crucial detail those hints can't: which operations overwrite (list fields replace) versus append (add_next). It also discloses the admin escalation path. It stops short of describing what publish does to visibility or what a rejected update looks like.

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 core action and permissions, then the non-obvious replace/append rule. Dense with no filler, though the parenthetical about admin rights interrupts the field enumeration slightly.

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

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

For a 13-parameter mutation with a fully described schema and safety annotations, the description covers the ambiguous parts: scope of authority and overwrite behavior. The publish, sections, and decisions semantics are left entirely to the schema, which is acceptable given 100% coverage and no output schema.

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

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

Schema coverage is 100%, so all 13 parameters are already documented, including the replace/append distinction. The description reinforces the add_next choice but adds no format, cardinality, or interaction detail beyond what the schema states, 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 verb 'change' and resource 'a share you made' are concrete, and the description enumerates the editable surfaces (title, summary fields, audience, PR link, visibility). It doesn't name a sibling, but no other tool in the list is an edit on an existing share, so confusion risk is low.

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?

'a share you made (or any share, if you're an admin)' gives real authorization context, and the add_next note guides selection between two similar parameters. However, there is no explicit when-not-to-use case and no pointer to an alternative tool for creating a share versus editing one, so routing is only implied.

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