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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds genuine behavioural context beyond that: it never spends money, it adds to a private library, and a paid listing yields status=payment_required with price and listing URL. It does not explain idempotent re-acquire behaviour, but the annotation 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 sentences, zero filler, with the entitlement scope front-loaded and the no-purchase guarantee immediately after. Every clause carries decision-relevant 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?

There is no output schema, and the description usefully foreshadows the paid-listing response shape (status=payment_required, price, listing URL). For a low-risk, annotated mutation with one required param, this is nearly complete; only the success-path result and the version parameter's meaning are unstated.

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

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

Schema coverage is 67% – id and tenant carry descriptions, version has only a default of 'latest'. The description adds no parameter-level meaning at all (no syntax, no source guidance), so it neither compensates for the gap nor improves on the schema. Baseline 3 for a mostly-documented 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?

Names a specific verb+resource ('Add a marketplace session ... to your private library') and scopes it by entitlement (free, bought, granted). An agent can distinguish this from search_sessions, publish_session, and the purchase-related siblings 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?

States the qualifying condition clearly ('sessions you are entitled to') and rules out the paid case ('Never buys anything ... returns status=payment_required'). It gives clear context for when this is the right tool, but never names the alternative an agent should reach for instead (e.g. request_purchase), so the routing guidance is inferential rather than 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the content is injected as conversation context and is token-sized, which is meaningful beyond the annotations, but it does not restate the elision behavior (that lives in the schema) or note auth/library prerequisites.

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 with a tight parenthetical covering id provenance; the tool's action and its sizing behavior appear before any qualifier. Nothing extraneous.

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 not need to explain return values, and annotations carry the read-only/idempotent profile. The one remaining gap is the undocumented `version` parameter and no explicit statement of what happens on a missing or unauthorized id, but the essentials for correct invocation are 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 75%, so the schema already documents id, max_tokens, and include_tool_calls; only version is undocumented in both places. The description echoes max_tokens sizing but adds no syntax, format, or default guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb+resource (load a session from your library) and the effect (as starting context for this conversation), plus the sizing constraint (max_tokens). It is clearly distinguishable from siblings like get_session_summary (summary only), search_sessions (discovery), and acquire_session (which adds sessions to the library).

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 explains the provenance of the id (saved sessions or the library_id returned by acquire_session), which gives the agent context for when this tool applies. It stops short of explicit when-not guidance or naming a competing tool to prefer instead, so it is clear context without 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral value of disclosing that the response includes price and an access check, but says nothing about auth requirements, rate limits, or failure modes when the session is unknown.

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 purpose front-loaded and the source hint appended. Every clause carries information, though 'Describe one session before using it' is slightly awkward phrasing.

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 tool with no output schema, the description usefully previews the summary contents (activity, outline, price, access), which is what an agent needs to decide whether to call acquire_session next. Minor gaps around the optional tenant parameter and error behavior keep it from 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?

With only 33% schema description coverage, the description must carry more weight. It clarifies the 'source' parameter ('marketplace (default) or library'), which is already implied by the enum and default in the schema, and says nothing about 'tenant' or the 'id' format. Partial compensation, baseline-level performance.

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 ('describe one session') and enumerates the returned facets (what it did, outline, price, access), which distinguishes it from fetch_session_context and acquire_session. It stops short of explicitly naming those siblings, so differentiation is inferable 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?

'Describe one session before using it' implies a pre-flight check that precedes acquire_session or actual use, which is useful implied guidance. However, no alternative is named and no exclusion or precondition (e.g., what to do if access is missing) is 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 only cover the safety quadrants (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds genuinely non-obvious behavior: the server scrubs token-shaped secrets before storing, and the stored session is private and never listed publicly by this tool. It omits auth requirements, size limits, and what happens on a content_sha256 mismatch, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the action and resource, no filler. The final privacy sentence partially duplicates the visibility enum's own 'Always private' description, which is the only mild redundancy.

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

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

For an 8-parameter write tool with no output schema, the definition covers purpose, scrubbing, and privacy but says nothing about what the call returns (library id / lineage handle), authentication requirements, or failure modes such as hash mismatch. Reasonably complete but with clear gaps an agent would want filled.

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 63%, so the schema already documents parent, transcript, visibility, content_sha256, and client_scrubbed. The description only re-touches the transcript format and the scrubbing that relates to client_scrubbed, and adds nothing about label, title, or idempotency_key. This matches the baseline for moderate 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 states a specific verb+resource and scope: 'Save a session transcript (JSONL) to your private a4sx library.' That clearly separates it from read-side siblings like search_sessions, get_session_summary, and acquire_session. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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 (save a transcript when you want to persist it), and the closing line hints that public listing is a separate web-app step, but there is no explicit when-to-use/when-not statement, no precondition guidance, and no named alternative such as acquire_session. Adequate but leaves routing 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 carry readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description still adds real context beyond structured fields: these are vetted, reviewed marketplace listings, and the output is ids intended for subsequent tools. It does not describe pagination behavior, but that is minor given the annotation coverage.

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

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

Two tight sentences, front-loaded with the primary scope and immediately followed by the return-value note. No filler, nothing redundant.

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

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

For a 7-param, no-output-schema search tool, the description covers purpose, both scopes, and the return shape (ids for other tools). It omits pagination/sort hints, but the schema handles those, so nothing essential to correct invocation is missing.

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

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

Schema description coverage is only 43% (sort, tags, limit, offset undocumented), so the description must carry some weight. It reinforces the scope semantics ('reviewed marketplace listings' vs. 'your own saved sessions') but largely restates what the schema's scope description already says, leaving the four undocumented params untouched.

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 (Search) and resource (coding-agent sessions), and splits the resource into two clearly named modes: vetted marketplace listings vs. scope=library saved sessions. An agent can tell this apart from the fetch/get siblings 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?

Distinguishes the two operational modes (public marketplace, no sign-in vs. library needs library:read) and signals this is the entry point by noting it 'Returns ids to use with the other tools.' It stops short of explicit when-not-to-use guidance or naming the sibling that consumes those ids.

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