a4sx sessions

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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is low. The description adds genuine behavioral value by disclosing the full outcome space (pending, completed, declined, expired) and noting that a completed request carries an acquired_copy_id, which the annotations cannot convey.

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 dense sentence, front-loaded with the resource and its outcome states, with the follow-up action packed into a parenthetical. 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?

With no output schema, the description does its job by enumerating the returnable status values and the one meaningful payload field (acquired_copy_id). It omits where the purchase_request_id originates and any polling/expiry semantics, which keeps it just short of fully self-contained.

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

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

Schema description coverage is 0% and the single parameter is required, so the description must carry the burden. It conveys the id's provenance ('a purchase you requested') but adds no format or shape detail beyond the pattern already present in the schema, leaving it only partially compensating.

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 the exact resource returned (the status of a previously requested purchase) and enumerates the four possible outcomes, which lets an agent distinguish it from the sibling request_purchase that initiates a purchase. It stops short of explicitly naming the initiating/alternative tool, so differentiation is implied rather than spelled out.

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 clear operational context: call this to check on a purchase you already requested, and when the result is 'completed' use the acquired_copy_id with fetch_session_context. It names the follow-up sibling and the condition that triggers it, though it never states outright when to prefer this over request_purchase or how often to poll.

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?

Beyond the annotations, the description discloses important behavior: the server only rewrites text matching secret and personal-data patterns, removes no record or field, preserves raw transcript carriers, and counts them in unprepared_carriers. It also clarifies that the saved session remains private and is not publicly listed by this tool, which is exactly the kind of context an agent needs.

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 purpose is front-loaded in the first sentence, and most of the detail is behaviorally relevant rather than redundant. However, the middle sentence is very dense and references external GET /orient route steps, making the description longer and harder to scan than necessary.

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

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

For a save operation with no output schema, the description covers the essential behavior: preparation steps, scrubbing scope, non-removal of records, and privacy. It still leaves some gaps around the full response shape and several individual parameters, but it is largely complete 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 67%, so the schema already documents several parameters. The description adds useful meaning around transcript format, markdown composition, and private visibility, but it does not explain label, title, parent, content_sha256, client_scrubbed, or idempotency_key beyond what the schema provides.

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: saving a session transcript or composed markdown to a private a4sx library. It is clear what the tool does and how format=markdown differs, but it does not explicitly distinguish itself from sibling tools such as search_sessions or fetch_session_context.

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 and prerequisite: prepare the transcript or compose markdown first according to GET /orient route A or route B steps 0-8. It does not state explicit when-not-to-use conditions or name alternatives, so it falls 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?

Adds substantial context beyond annotations: 'Nothing is charged and you never pay,' the two-phase async flow, the returned verify_url and user_code handed to the account holder, and the required human confirmation before payment. This tells the agent this is not idempotent in practice and must be followed up, which the hints alone do not convey.

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. The most important fact (no charge, agent never pays) is front-loaded, followed by the return values and the required follow-up call.

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

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

No output schema exists, yet the description explains what is returned (verify_url, user_code) and the lifecycle continuation (poll get_purchase_request), plus the human-in-the-loop requirement. Nothing an agent needs to invoke and correctly handle this tool 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%, so id, tenant and version are fully documented in the schema (including provenance from search_sessions and the default for version). The description adds no parameter-level detail, 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 a specific verb+resource ('Start buying a paid marketplace listing') and immediately scopes it: it is a request step, not an actual purchase. This is clearly distinguishable from search_sessions (find listings) and get_purchase_request (poll status), which it names.

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 context for use ('for the account holder to confirm') and an explicit next step: 'Then poll get_purchase_request.' It does not state a when-not condition, but no sibling overlaps this write-style action, so the routing is 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 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.