Synoptic

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

Annotations already cover the write profile (readOnlyHint=false, destructiveHint=false) but do not explain the semantics of non-evaluation or that update_collection replaces the whole configuration. The description surfaces both, which is real behavioral value beyond the annotations; it stops short of noting non-idempotency or the response shape.

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 dense sentences, front-loaded with the core action and the key 'without evaluating it' caveat. Slightly packed with cross-references, but every sentence carries load.

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 an output schema present, return values need not be explained, and the description still references the returned id for chaining. It covers creation semantics, the idempotency-adjacent 'no evaluation' behavior, and the update alternative, leaving no gap for an agent to call it correctly.

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

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

Schema description coverage is 100% and both params (name, prompt) are documented in the schema with constraints, so the baseline is 3. The description adds no parameter-level meaning beyond describing the lazy-evaluation behavior of prompt.

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 ('Save a named AI filter prompt for the signed-in user') and clarifies the non-obvious scope 'without evaluating it'. It distinguishes itself from update_ai_filter by name, so an agent can route correctly 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?

Gives explicit next-step usage ('Attach the returned id through filters.ai in create_collection, or in update_collection') and names the alternative for the modify case ('Use update_ai_filter to change an existing filter'). It also preempts a likely dead-end by stating no tool evaluates a prompt on demand.

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 declare the safety profile (destructiveHint true, non-idempotent, openWorld), and the description adds substantial beyond-schema behavior: auto-following eligible sources, possible invitation consumption, backfilling of stored posts, AI-allowance consumption, and that repeated successful calls create separate collections. This is exactly the side-effect disclosure an agent needs for a mutating 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?

Front-loaded with the core action and followed by side-effect caveats in separate, purposeful sentences. Dense but each clause carries information; only slight redundancy between the follow/backfill statements.

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 a rich output schema, full annotations, and 100% schema coverage, the description only needs to supply side-effect and scope context – which it does comprehensively. Nothing needed to invoke 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 description coverage is 100%, so the schema already documents all six parameters thoroughly (filters.ai, regex, highlights, sources, etc.). The description adds the AI-filter/allowance context but no parameter syntax or format details beyond that, so the 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?

States a precise verb+resource ('Create a collection in the signed-in user's stream deck from existing Synoptic streams') and clarifies the return ('collection metadata'), which distinguishes it from siblings like create_stream, create_stream_deck, and create_stream_post.

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?

Provides real usage context: it explicitly says what the tool does NOT do ('Does not purchase stream access or create upstream collectors'), which routes agents away from wrong expectations. It stops short of naming a sibling alternative or stating when-not-to-use it, so it is clear context without explicit 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 cover the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds that the result is a draft, that ownership is bound to the signed-in user, that the stream is free, and that paid pricing is out of scope — context not present in the annotations. It stops short of stating auth/permission requirements or duplicate-name 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?

Three sentences, front-loaded with the core action before the workflow and exclusions. Dense but every sentence carries routing or constraint information; the middle sentence about custom-target tools is the most compressed.

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 an output schema present, return values need not be described. The description covers the create-publish lifecycle, ownership, and scope exclusions, which is sufficient for a creation tool whose annotations and schema carry the rest.

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 six parameters including the two enums are already documented. The description only reinforces that the description field is plain text (Markdown not rendered), adding marginal value beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource — create a free draft publishing stream owned by the signed-in user — plus the scope (research, news, other updates). It distinguishes itself from publish_stream and request_stream, so an agent can tell it apart from siblings 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?

Gives an explicit workflow: add a first post with create_stream_post, then publish with publish_stream. It also names alternatives and exclusions — existing custom-target tools for source monitoring, request_stream for new coverage, and 'does not configure paid pricing'.

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 this is a non-read-only, non-idempotent, non-destructive write. The description adds real context beyond them: the deck is created empty, its ID is returned, and there is a hard quota of 25 decks per account. It does not mention auth/permission requirements beyond 'signed-in user'.

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 and return value, then follow-up steps and limits. No sentence 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?

An output schema exists, so return details need not be repeated, yet the description still notes the ID is returned. For a single-parameter create tool with a quota and clear follow-up routing, nothing an agent needs 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 description coverage is 100% and there is only one parameter ('name'), which the schema already documents as trimmed and non-unique. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Create an empty stream deck') and even clarifies what a deck is ('a dashboard of collection columns') plus its scope ('for the signed-in user'). It distinguishes itself from siblings by naming create_collection for columns and update_stream_deck for renames.

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: add columns via create_collection, rename via update_stream_deck, and states the 25-deck account limit. It stops short of explicit when-not-to-use guidance (e.g., that existing decks should be fetched with list_stream_decks), so it 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 only give generic hints (readOnly=false, idempotent=false, destructive=false); the description supplies the substance behind them: followers may be notified, timestamps are platform-assigned, and posts cannot be edited or deleted through MCP. That side-effect and irreversibility disclosure is exactly the context annotations cannot carry.

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, followed by the side-effect caveat and the sibling routing. No filler or restatement of the title.

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?

An output schema exists, so return values need not be described. Given the write is irreversible per the description, the agent has everything needed: ownership scope, notification side effect, timestamp behavior, and the alternative tool for a different goal.

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 non-obvious customTarget rule (required on custom-target streams, rejected elsewhere), so the schema already does the heavy lifting. The description adds no parameter-level detail beyond 'text post', which is the correct baseline 3.

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

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

States a specific verb and resource ('Add a text post to a stream') plus a scope constraint ('owned by the signed-in user'). It also names the adjacent tool publish_stream, so an agent can tell posting apart from going live 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?

Explicitly routes the agent to publish_stream when the goal is taking a draft stream live, which resolves a plausible confusion. It stops short of stating when-not to use this tool or listing prerequisites for posting itself, so it is clear context rather than 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's job is lighter. It adds useful scope context: 'Stores layout only; does not place trades.' It does not disclose duplicate-name behavior or error/repeat-call semantics, but the core behavioral trait is clear.

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 scope, followed by the sourcing tip and the scope clarification. Every clause earns its place with no 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?

With an output schema present, return values need no explanation, and the two required parameters are covered by the schema. Purpose, config sourcing, and the 'stores layout only' scope are all present, so an agent has everything needed to call it 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% and both parameters are fully documented in the schema, so the baseline is 3. The description reinforces that 'configuration' is a serialized layout JSON string and points to list_terminal_tabs as a source, but adds no syntax or format detail 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?

States a specific verb and resource ('Create a terminal tab') plus scope ('for the signed-in user') and the input form (saved layout JSON serialized as a string). It also differentiates from siblings by naming list_terminal_tabs as the preferred config source and clarifying it 'does not place trades', disambiguating a create_tab write from any trading action.

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?

'Prefer copying an existing tab configuration from list_terminal_tabs' gives clear, actionable guidance on where to source the configuration. It stops short of stating when to use this versus update_terminal_tab (e.g., new tab vs. modifying an existing one), so no explicit exclusion is provided.

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 readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the side effect that collections using the filter are detached and stop applying it — information not present in the annotations or 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?

Two short sentences, no filler, with the primary action front-loaded and the consequence following immediately. Every clause earns 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?

With annotations covering safety/idempotency and an output schema present, the description only needs to convey the destructive side effect, which it does explicitly. Nothing required to invoke this 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 description coverage is 100%; the single id parameter is documented in the schema ('AI filter ID from list_ai_filters') with length bounds. 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 (delete) plus resource (AI filter), and constrains scope to filters 'owned by the signed-in user', which distinguishes it from generic delete tools in the sibling list. The cascade effect on collections is named, so the action's blast radius 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?

Deletion intent is clear from the verb, but there is no explicit when-to-use guidance and no alternatives are named (e.g., update_ai_filter to modify rather than remove, or list_ai_filters to find the ID). Usage is implied 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: the exact blast radius (saved versions and source configuration are destroyed) and what survives (original stream posts and follows), plus the ownership constraint. It stops short of mentioning permissions or irreversibility confirmation, so not a full 5.

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

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

Three sentences, front-loaded with the action and its destructive scope, followed by preservation guarantees and then routing to alternatives. Every sentence carries distinct information with no 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 a two-parameter destructive tool with an output schema, the definition covers the action, the destruction boundary, the preservation boundary, ownership, and alternative tools. Nothing an agent needs in order to call it correctly or avoid misusing it 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 both parameters point at their upstream list tools (list_collections, list_stream_decks), so the schema already carries parameter meaning. The description adds only the implicit ownership constraint on the collection and no new syntax or format detail. 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?

States a specific verb (delete), resource (custom collection), ownership scope (owned by the signed-in user), and precisely what is removed (saved versions, source configuration) versus preserved (original stream posts and follows). It explicitly names the sibling it is not (delete_stream_deck, update_collection), so an agent can disambiguate 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 explicit routing: use delete_stream_deck to remove the whole deck, and update_collection to change sources or filters. Both the alternative tools and the conditions that select them are stated, leaving nothing 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?

Goes well beyond the annotations: it enumerates concrete side effects (unfollows followers, sends notifications, removes the stream from collections, API key publish permissions and source routes) and states irreversibility ("cannot be undone"). The annotations only supply destructiveHint/idempotentHint, so this detail is genuinely additive.

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 action and scope, followed by consequences and restrictions. Every clause carries operational information; 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?

For a destructive single-parameter tool with an output schema, the description covers everything an agent needs: eligibility, side effects, irreversibility, and the blocked case. Return values are already handled by the 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 baseline is 3, but the description adds real constraint semantics: the ID must be exact and must belong to a free stream the caller owns. That is more than restating the schema's "ID of a free stream you own, from streams_created."

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 ("Delete an owned free stream") and immediately scopes it to free streams the caller owns, which cleanly separates it from the other delete_* siblings (delete_ai_filter, delete_collection, delete_stream_deck, delete_terminal_tab). An agent can pick this tool 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 when-to-use conditions (owned, free stream) and an explicit when-not (paid streams must be deleted in the Synoptic app), plus the precondition that the exact stream ID is required. It stops short of routing the agent to the nearest alternative, unfollow_stream, for the non-destructive case.

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 the crucial cascade scope (all custom collections in the deck are destroyed), the explicit non-effect ('does not delete the original stream posts'), and a hard precondition (last deck is undeletable). This is exactly the beyond-annotation context the dimension rewards.

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, each load-bearing: scope, precondition, non-effect, alternative. The destructive scope is front-loaded and there is no filler.

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

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

With an output schema present, return values need no explanation, and the description covers the destructive cascade, the exception case, and the safer sibling. Nothing an agent needs to call this 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?

There is only one parameter and schema coverage is 100%; the schema itself documents 'id' as the Deck ID from list_stream_decks. The description adds no format, validation, or sourcing detail beyond what the schema already 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?

States a specific verb (delete) plus resource (stream deck) and immediately scopes it: owned by the signed-in user, and every custom collection inside it. An agent can distinguish it from delete_collection, delete_stream, and delete_ai_filter 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 an explicit when-not (the last remaining deck cannot be deleted) and names the alternative tool with the condition that selects it: 'Use delete_collection to remove one collection and keep the deck.' Routing is fully determined.

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, so the safety profile is covered. The description adds value beyond them by disclosing the non-obvious collateral effect (the saved layout is destroyed too) and a business rule (the last tab is protected), which the 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?

Two tight sentences: the action and its destructive scope first, then the constraint, then the alternative. Every clause earns its place 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?

For a single-parameter destructive tool with an output schema and annotations that already flag destructiveness, the description covers what is destroyed, what is prohibited, and where to go instead. Nothing an agent needs 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?

Only one parameter and schema description coverage is 100% ('Tab ID from list_terminal_tabs'), so the schema fully carries parameter meaning. The description adds an ownership scoping implication but no format or sourcing detail beyond the schema, which is the expected baseline here.

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 (Delete), resource (terminal tab), and scope (owned by the signed-in user), plus the side effect that the saved layout goes with it. It also names the sibling update_terminal_tab and distinguishes its purpose, so an agent can separate this from the other terminal tools without opening schemas.

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 routes the agent explicitly to update_terminal_tab for layout changes, which is real when-to-use-this-instead guidance. It also states the platform-level constraint that the last tab cannot be deleted, though it doesn't state prerequisites such as required access level beyond 'owned by the signed-in user'.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: public cards need no sign-in while private cards require a linked account with access. It stops short of describing failure behavior (nonexistent ID, private card without access), which keeps it out of 5 territory.

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 clauses with the core action front-loaded, then auth constraints, then sibling routing and scope exclusions. No filler sentences and nothing repeated across sentences.

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?

An output schema exists, so return values need not be explained, and the description still summarizes the payload. Auth requirements, negative scope and sibling routing are all present for a one-parameter read tool. Only error/edge-case behavior for missing or inaccessible cards is absent.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the baseline is 3. The description restates that the lookup is by ID and clarifies the object is a stream card, but adds no format, type, or sourcing detail beyond the schema, and there is mild ambiguity about whether the ID is a stream ID or a card 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?

States a specific verb and resource ('Read a Synoptic stream card by ID') and enumerates the returned fields (title, description, stream URL). It also distinguishes itself from the two closest siblings, get_stream and get_stream_posts, so an agent can select it 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 explicit alternatives with their selection condition ('get_stream for more metadata', 'get_stream_posts for posts after signing in') and an explicit negative scope ('Does not fetch arbitrary URLs or articles'). Both when-to-use and when-not-to-use are covered.

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/idempotentHint/openWorldHint, and the description adds genuinely new context: follow permission is required, no subscription is purchased, and an existing invitation may be consumed and will not be restored by unfollowing. The irreversible invitation consumption is exactly the kind of trait annotations cannot express.

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 trigger before the caveats. The clause 'when the user asks to follow that stream' is mildly redundant with the tool name 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?

Return values are covered by the output schema, and for a single-param mutation the description supplies the essential missing context – permission requirement, subscription behavior, and irreversible invitation consumption. Little an agent needs to call it correctly is absent.

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?

Only one parameter, and the schema already documents it at 100% coverage ('The id of the stream to follow'). The description adds no format or source detail for id, so this is the baseline 3.

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

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

States a specific verb and resource (follow a Synoptic stream), clearly distinct from sibling follow_user and from unfollow_stream. It stops short of explicitly naming those siblings as alternatives, but the stream-vs-user scope 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?

"When the user asks to follow that stream" is an implied trigger rather than a real decision rule, and it doesn't contrast with alternatives like request_stream or unfollow_stream. The invitation note gives a partial hint about when the call has side effects, but no explicit 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?

Annotations only tell the agent this is a mutating, open-world, idempotent, non-destructive write. The description adds substantial context beyond that: the follow may trigger notifications via email or push depending on author settings, and it returns success=false when already following or on failure. This is exactly the kind of side-effect and error semantics annotations cannot express.

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 earning its place: the action, the notification side effect, the error/return semantics, plus the sibling redirect. Front-loaded with the action and 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 single-parameter mutation with an output schema present, the description covers the side effects (notifications), the key return/error condition (success=false when already following), and the sibling boundary. Nothing material 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% and the single userId parameter is already documented with format and provenance ('Synoptic user ID... such as id from get_user'). The description adds nothing about the parameter, so the 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?

States a specific verb and resource ('Follow an author') plus the acting identity ('as the signed-in user'), and explicitly names the sibling it differs from ('Use follow_stream to follow a stream'). An agent can distinguish it from follow_stream and unfollow_user without opening schemas.

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?

Clearly signals the alternative follow_stream for a different resource, so the agent knows when not to use this tool. It doesn't cover preconditions like checking is_following_user first, but the routing guidance is explicit for the main 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?

The description adds real behavioral context beyond the annotations: it discloses that the result is persisted ('save') and that it is destructive in a specific way ('These replace previous suggestions'). This explains what the destructiveHint=true annotation actually destroys, which annotations 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 short sentences, action and side effect first, follow-up tool second. No filler, 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?

For a zero-param mutation tool with an output schema and full annotation coverage of the safety profile, the description covers purpose, destructive side effect, and the follow-up call. It stops short of stating suggestion lifetime or availability-checking behavior, but nothing essential to invoking 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description neither needs nor omits parameter guidance.

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 pair (generate and save), the resource (username choices), the exact count (five), and the scope (signed-in user). It also places itself in the workflow by naming set_username as the consumer, so an agent can distinguish the generator from the applier.

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?

Makes the usage context clear: generate a set of options, then pass one to set_username. There is no explicit when-not guidance, but the generate-then-apply sequencing 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two pieces of context beyond that: ownership scoping to the signed-in user and the clarification that reading does not execute/evaluate the filter, which is a genuinely non-obvious behavioral boundary.

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 purpose is front-loaded and the exclusion clause follows immediately. Every sentence earns 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?

With full schema coverage, complete annotations, and an output schema handling return values, the description is nearly sufficient. It omits only edge behavior such as what happens when the ID does not exist or belongs to another user, which is a minor gap 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 coverage is 100% and the schema already explains that the id comes from list_ai_filters or a collection's aiFilterId, including length constraints. The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (one saved AI filter definition) with explicit scope ('owned by the signed-in user'), which cleanly distinguishes it from the sibling list_ai_filters. An agent can tell immediately this fetches a single record rather than enumerating.

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 implies the use case (retrieve one filter by ID) and adds a useful scope exclusion ('Does not evaluate the filter'), but it never explicitly routes the agent between this and list_ai_filters, create_ai_filter, update_ai_filter, or delete_ai_filter. 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful context: the ownership scoping ('owned by the signed-in user') and the granular contents of the returned configuration, clarifying this is a full-config read versus a posts read.

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: the first front-loads purpose and returned fields, the second handles sibling routing. No redundant or filler content.

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?

An output schema exists, so return structure need not be fully explained, and annotations carry the safety profile. The description still adds the ownership scope and config-vs-posts distinction, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, with both required parameters documented in the schema ('Collection ID from list_collections', 'Deck ID from list_stream_decks'). The description adds no syntax or format detail beyond the schema, 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 (Read) and resource (custom collection), scoped to the signed-in user, and enumerates what it contains (keyword filters, AI filter ID, source streams, custom targets). It explicitly distinguishes itself from update_collection and get_collection_posts, so an agent can separate it from siblings without opening their schemas.

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 routes the agent by naming alternatives and what each returns: this tool returns the full configuration that update_collection replaces, while get_collection_posts returns the posts. That is clear selection context, though it stops short of stating explicit when-not-to-use conditions.

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, so the safety profile is covered; the description adds genuinely useful behavior: access rechecking, empty-page-with-cursor semantics, and the 50-post page cap. It stops short of describing the returned post shape, though an 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 sentences, no filler, and the scope constraint (owner, 50-post cap) is front-loaded. The paging caveat is a legitimately necessary second half.

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 paginated, nested-filter read tool with a full schema and an output schema, the description covers the tricky parts an agent would otherwise get wrong: cursor continuation on empty pages and rechecked access. Return values are appropriately left to the 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 description coverage is 100%, including detailed nested matchFilter fields, so the baseline is 3. The description only summarizes the filter concept ('matched crypto or prediction markets') without adding syntax or semantics beyond what the schema already states.

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 ('Read up to 50 stored posts from a collection'), and adds scope ('owned by the signed-in user') plus optional market matching. It distinguishes itself implicitly from get_stream_posts and search_stream_posts by naming collections, but never names a 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?

Gives operational guidance for paging (continue with nextToken when a page is empty) and notes access is rechecked, but never says when to choose this over get_stream_posts or search_stream_posts, so the sibling choice 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, non-destructive, open-world behavior, so the description's marginal value is the implicit-scope rule (omit username = signed-in user) and the nextToken continuation pattern. It does not add anything about rate limits or result ordering, but with full annotation coverage that omission is minor.

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 filler. The core purpose and scope rule are front-loaded, and the sibling reference comes last, which is the correct priority order for an agent.

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 an output schema present, the description need not explain return values, and annotations cover the safety profile. Scope default, pagination, and sibling disambiguation are all covered, leaving nothing an agent needs in order to call this correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including username's 'omit for the signed-in user' and nextToken's 'omit for the first page'. The description restates those semantics rather than adding new ones (no page-size guidance or stability notes), 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 and resource ('List followers of a Synoptic username') plus the default scope when username is omitted. It also explicitly contrasts itself with get_following_users, so the agent can distinguish the two 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?

Names the alternative tool and the condition that selects it ('Use get_following_users for the authors a user follows'), and gives the pagination workflow ('Continue with nextToken'). Routing between the two closely-named siblings 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the result is paginated and continued with nextToken, and the call scope silently defaults to the signed-in user when username is omitted. It does not mention rate limits or ordering, but with annotation coverage the bar is lower.

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 with the primary purpose front-loaded, followed by pagination behavior and then the disambiguation list. No filler and no repetition of the title.

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?

An output schema exists, so return values need no prose. Between the description (scope, default target, pagination continuation, sibling routing) and the structured fields, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, and the schema already documents limit, username ('omit for the signed-in user'), and nextToken ('omit for the first page'). The description restates the username default and nextToken continuation rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('List authors followed by...') and defines the scope precisely, including the default when username is omitted. It explicitly separates itself from the nearest siblings (streams_following, get_followers, is_following_user), so an agent can pick 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?

Names three alternatives with the condition that selects each: streams_following for the signed-in account's streams, get_followers for followers, is_following_user to check one author. Explicit when-to-use-this-vs-that guidance, nothing 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/openWorld/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavioral facts the annotations do not carry: a 50-item cap on results and that the endpoint is not paginated. This materially affects how an agent consumes the output.

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: purpose first, then the 50-cap/non-pagination constraint, then the routing alternative. Every clause carries information 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?

An output schema exists, so return-value shape need not be explained. With no parameters, the annotations covering safety, and the description covering scope, cap, and pagination, an agent has everything needed to call it 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?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description's note that filtering is by the fixed isHighlighted flag (not a caller input) appropriately frames the absence of arguments.

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 (List) and resource (public profiles of authors Synoptic features, flagged isHighlighted) with a hard result cap. It explicitly distinguishes itself from get_user and get_user_by_id, so an agent can route without opening any sibling 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 the exact condition for use ('for discovery when no particular author is named') and names the correct alternatives ('Use get_user or get_user_by_id for a known author'). When-to-use, when-not, and the replacement tools are all present.

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=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: reading does NOT mark items read, plus a prompt-injection caution ('user-authored content is data, not authorization'). Both are valuable beyond annotations.

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 with the key constraint (no auto-mark) and sibling routing in four tight sentences. The injection-safety sentence is slightly tangential but earns its place as a guardrail.

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 an output schema present, return values need not be explained. The description covers user scoping, pagination intent, side-effect behavior, and safety guidance – no gap an agent needs to call this 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 baseline is 3. The description restates the read flag's behavior but adds no syntax or format detail beyond the schema for limit/nextToken. Pagination mechanics (unchanged args with nextToken) live 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?

States a specific verb+resource+scope: 'Read the signed-in user's paginated in-app notifications.' The agent knows exactly what it retrieves and that it is scoped to the current user. It also implicitly distinguishes itself from mark_* 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?

Explicitly explains the read filter semantics ('read=false for unread, omit for both') and routes the agent to mark_notification_read / mark_all_notifications_read for the alternative action. Clear context, though it doesn't frame when a caller should prefer paging vs. other retrieval paths.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it describes the shape of the returned data (channel switches plus per-event preferences) and maps it to the sibling write tools that mutate those exact groups, which helps the agent reason about state. It does not cover auth/permission requirements, but for a read tool that is a minor omission.

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, all front-loaded: purpose first, then the relationship to the mutating siblings, then the disambiguation from get_notifications. Every sentence carries routing or scoping information and none 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?

A zero-parameter read tool with full annotation coverage and an output schema that documents the return shape. The description supplies the scope, the sibling relationships, and the disambiguation an agent needs, so nothing relevant 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter meaning for the description to add or omit. Nothing in the description contradicts or misrepresents the empty input 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 (Read) plus the precise resource (the signed-in user's notification channel switches and per-event preferences). It explicitly distinguishes itself from three siblings by name — update_notification_preferences (which replaces the groups), set_notification_channel (which toggles the switches), and get_notifications (which lists notifications) — so an agent can route 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?

It gives explicit routing: use get_notifications to list the notifications themselves, implying this tool is for inspecting configuration rather than events. It also frames itself as the read counterpart to the two write siblings. It stops short of stating when-not to use it (e.g. before updating settings), so it is clear context rather than 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the visibility/permission rules that determine success or failure, and an explicit negative scope about external article URLs.

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, purpose front-loaded, then access rules, then negative scope. Every sentence carries a distinct constraint; nothing is repeated from the title or 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 single-parameter read tool with an output schema (so return values need no explanation), the description covers purpose, access prerequisites and out-of-scope behavior. An agent has everything needed to call it correctly or recognize a permission failure.

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?

Only one parameter and schema description coverage is 100% — the schema already documents the id and even points at the tools that produce valid IDs. The description's 'by ID' adds nothing the schema does not, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read an existing stream post by ID'), which separates it from the plural list siblings (get_stream_posts, get_collection_posts) and from search_stream_posts. The closing clause 'Does not fetch external article URLs' further fences it off from the generic fetch tool.

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 explicit access conditions: public posts need no following, private posts require individual-post access, and custom-target restrictions still apply. It stops short of naming a sibling to use instead when access fails (e.g. list/search tools), so it is clear context without 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), and the description adds the genuinely non-obvious behavioral fact: public streams need no sign-in while private streams require a linked account with access. The enumeration of returned fields (description, publication state, API-access flag, pricing, custom-target instructions) is largely duplicative of the output schema, so it stops 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?

Four tight sentences, front-loaded with the purpose, then scope bound, then return content, then auth prerequisite, then the exclusion. No filler and no repetition of the title.

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-parameter read tool with an output schema, rich annotations and a clear sibling neighborhood, the description covers purpose, prerequisites, return shape and exclusions. Nothing an agent needs 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?

With one required parameter at 100% schema coverage, the baseline is 3. The description adds useful semantics beyond the schema by telling the agent where the ID comes from (search or streams_all) rather than just that an 'id' string is required.

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 ('Inspect a discovered Synoptic feed by ID') and immediately bounds scope with 'Does not return posts or follow the stream', which cleanly separates it from get_stream_posts, search_stream_posts and follow_stream. An agent can distinguish it from all ~70 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 explicit when-to-use framing ('before reading, configuring monitoring targets, or planning an API integration'), names the discovery alternatives ('Use search or streams_all to find an ID'), and states an explicit non-use case (no posts, no follow). Nothing material 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 declare readOnlyHint and non-destructive, so safety is covered. The description adds important context not in annotations: followers see their own selections while the owner sees the union, and it explicitly excludes collector health/delivery timing. This is meaningful behavioral disclosure beyond 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?

Three focused sentences, front-loaded with the core purpose, then usage guidance, then scope clarification. No filler; every sentence adds value.

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?

An output schema exists so return values needn't be explained. For a read-only 1-param tool, the description covers purpose, format routing, visibility semantics (follower vs owner), and explicit non-scope (health/timing). Nothing an agent needs to invoke 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?

One parameter (streamId) with 0% schema description coverage. The description implies the stream must be 'accessible' and owned/followed, which adds usage context for the ID, though it doesn't detail format constraints. With only one param and no explicit schema description, the description partially compensates.

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?

Specific verb ('Read') and resource ('custom-target values') with examples of what those values are (accounts, channels, repositories, tracking criteria). Distinguishes itself from sibling get_stream by explicitly routing to it for target-format instructions.

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?

Clear usage context ('Confirms saved selections, not collector health or delivery timing') and names get_stream for format guidance. Lacks explicit when-not-to-use (e.g., when to prefer patch_stream_custom_targets or set_stream_custom_targets), but the routing to get_stream covers the main 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the bar is lower, yet the description adds real behavioral context the annotations cannot: visibility is permission-dependent ('Non-owners see active included streams only') and it states what it does not do (no posts, no subscription). It stops short of describing auth requirements or error/pagination 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?

Three short sentences, front-loaded with what is returned, then the visibility rule, then the exclusions. No filler, and each clause carries distinct 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 one-parameter, read-only tool with a full output schema and rich annotations, the description covers purpose, visibility nuance, and scope boundaries. The return shape is covered by the output schema, so the only minor gap is any auth/error context, which is not critical here.

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

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

Schema description coverage is 100% and the single 'id' param already documents its source (list_stream_packages or list_my_stream_packages). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

Specific verb+resource: 'Read a stream package, its available prices, and included stream cards,' enumerating the returned content. The closing clause 'Does not return stream posts or subscribe to the package' explicitly separates it from get_stream_posts and the *stream_subscription tools, so an agent can tell it apart from siblings without opening schemas.

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 required 'id' and by the negative clause 'Does not return stream posts or subscribe to the package,' which is a weak when-not rather than a routing rule. It never says when to pick this over get_stream, get_stream_package_subscription, or list_stream_packages, so the agent must infer.

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 covered. The description adds genuine behavioral context beyond that: the null return when no subscription exists, and the fact that mutation is out of band in the Synoptic app. It stops short of describing pagination or error behavior, so a 4 rather than 5.

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

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

Three short sentences, front-loaded with the core purpose, then the null case, then routing guidance. Every sentence carries distinct information 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?

With an output schema present the description needn't spell out return fields, yet it still flags the null case. For a single-parameter read tool with full annotation coverage, nothing needed to invoke or route the tool 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?

There is one parameter and schema description coverage is 100%, with the schema already telling the agent where the package ID comes from (list_stream_packages or list_my_stream_packages). The description adds no format or constraint detail 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 (read) and resource (signed-in user's paid subscription status for a stream package) and enumerates the payload (price, scheduled cancellation). It explicitly distinguishes itself from the sibling get_stream_subscription by scoping to packages versus a direct stream subscription.

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?

Names the alternative (get_stream_subscription) and the condition that selects it (a direct subscription to one stream), and further rules out write operations by stating subscribing/changing/cancelling happens in the Synoptic app. Both when-to-use and when-not-to-use 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 cover the safety profile (readOnly=true, destructive=false, openWorld=false), yet the description adds real context: requires authentication and read permission, custom-target restrictions apply, and pages are capped with a continuation token. It does not mention rate limits or failure modes, so a 4 rather than 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?

Four tight sentences, purpose front-loaded, followed by permission requirements, return/pagination shape, and sibling routing. No filler or repetition of the title.

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 an output schema present, the description does not need to explain return values, and it still supplies the operational essentials an agent needs: auth/permission requirement, page size limit, continuation token semantics, ordering, and when to pick an alternative 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 the schema already documents id, limit, toDate, fromDate, and nextToken with formats and bounds. The description only frames the parameters' purpose ('date bounds for historical updates', 'optional continuation token') without adding syntax or constraint detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Read one page of stored posts from an accessible Synoptic stream, newest first'), including scope and ordering. It distinguishes itself from siblings by explicitly naming search_stream_posts and by negating monitoring/external-fetch behavior.

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 routing conditions: use date bounds for historical updates, use search_stream_posts for text queries. It also states the boundary condition that this call reads existing content only and does not start monitoring or fetch external sources.

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, so the safety profile is covered. The description adds genuinely non-obvious behavior: a null subscription does not imply no access (package/org routes exist), and mutations occur out of band in the app. That is useful context beyond structured fields, though return-shape details are left to the output 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 is read, followed by the null caveat and the alternative/mutation routing. No filler and no repetition of the schema 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 an output schema present, return formatting need not be restated. The description covers scope, the null-result interpretation, the sibling alternative, and where mutations live, which is everything an agent needs to call this 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 streamId is fully documented in the schema, including where to obtain the ID (search, streams_all, streams_following). The description adds nothing further about the parameter, which is the expected baseline when the schema carries the field 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 (Read) and resource (the signed-in user's direct paid subscription status for a stream), and enumerates the fields returned (price, scheduled cancellation). It explicitly distinguishes itself from the closest sibling, get_stream_package_subscription, so an agent can route 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?

Gives explicit routing: use get_stream_package_subscription for package-based access, and states that subscribing/changing/cancelling happens in the Synoptic app, i.e. this tool is not the mutation path. It also tells the agent how to interpret a null result, which is the main usage trap.

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, openWorld and non-destructive, so safety is covered. The description adds useful context beyond them: only public profiles are returned, and the unknown-username outcome is spelled out. It does not describe rate limits or auth requirements, but with annotations carrying the safety profile the remaining gap is minor.

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 filler. The primary operation comes first, routing alternatives second, and the error behavior last – a well front-loaded 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?

A single-required-parameter read tool with an output schema and full annotation coverage needs little else. Return-shape explanation is unnecessary because the output schema exists, and the description covers scope, routing, and the error case.

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 schema already documents case-sensitivity, the absence of '@', and the display-name exclusion. The description's 'exact username' reinforces the schema's constraint but adds no new syntactic or format detail, so the baseline 3 is correct.

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 ('Read') plus a precisely scoped resource ('public Synoptic profile by exact username'), and the word 'public' narrows what data is returned. It is immediately distinguishable from siblings like get_user_by_id and get_me.

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 routes the agent: use get_user_by_id for an ID such as a stream's authorId, and get_me for the signed-in account. It also states the failure condition ('Unknown usernames return User not found'), so the agent knows what an unsuccessful call looks like.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the profile is 'public' (implying private/restricted users may be invisible or partial) and unknown IDs return 'User not found' rather than an empty object. It stops short of saying whether a non-existent-but-valid-format ID differs from a malformed one.

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 filler. The positive capability comes first, then routing to alternatives, then the error case — well front-loaded for scanning.

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 an output schema present, return shape need not be described. For a single-parameter read tool with full annotation coverage, capability, sibling routing, and error behavior are all present; nothing an agent needs to invoke 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 description coverage is 100% and the single userId parameter is fully documented there, including where IDs come from (stream authorId, get_followers). The description adds no syntax, format, 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?

States a specific verb and resource ('Read a public Synoptic profile by user ID') and immediately scopes it against the two nearest siblings, get_user (by username) and get_me (signed-in account). An agent can distinguish this tool from every other get_* sibling 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?

Explicitly names the alternatives and the condition that selects each one: use get_user when you have a username, get_me for the signed-in account, otherwise this. It also states the failure condition for an unknown ID, which removes ambiguity about retrying.

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 safety is covered. The description adds the non-obvious constraint that the check is implicitly scoped to the authenticated viewer and cannot be used to test an arbitrary viewer-author pair, which is real behavioral value beyond the annotations; it stops short of noting what a negative result looks like, though the output 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, zero filler, with the scope constraint front-loaded before the pointer to the alternative tool. Every clause carries information the 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?

The tool is a single-parameter read with rich annotations and a declared output schema, so return semantics need not be described. Scope, the alternative route, and the parameter's origin are all covered, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100% and the single parameter's description ('Synoptic user ID of the author, such as id from get_user') already supplies format and provenance. The description adds nothing about the parameter beyond what the schema says, so the baseline 3 applies.

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

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

States a specific verb+resource pair ('Check whether the signed-in user follows a given author') and immediately bounds the subject to the signed-in user, which separates it cleanly from get_following_users, follow_user, and unfollow_user in the sibling list.

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 states the scope condition ('Checks only the signed-in user') and names the alternative to use instead for a broader listing ('use get_following_users to list a user's follows'). The agent knows both when to pick this tool and which sibling to pick otherwise.

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 still adds real value by clarifying the scope (the signed-in user's saved definitions) and that no filter evaluation happens, which 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?

Two short sentences with zero filler. The core action and scope come first, and the single exclusion follows, so an agent gets everything it needs 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 0-parameter read tool with an output schema, the description need not explain return values, and annotations cover the safety profile. Nothing essential is missing, though it could note ordering or volume expectations for the returned list.

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 no parameter semantics for the description to cover; the baseline for a 0-param tool is 4. Schema coverage is 100% and the description adds nothing misleading about inputs.

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 (List) and resource (saved AI filter definitions) scoped to the signed-in user. It is clearly distinguishable from get_ai_filter (singular) and the create/update/delete variants, though it never names those siblings explicitly.

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

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

The second sentence gives an explicit exclusion - 'Does not run or evaluate filters' - which steers the agent away from mistaking this for an execution tool. It stops short of naming get_ai_filter as the alternative for retrieving one filter, so it falls just below 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 cover readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully handled structurally. The description adds genuine extra behavior: results are scoped to the signed-in user and returned in display order, which the annotations 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 compact sentences, zero filler. The core action and scope are front-loaded, and the alternative-tool routing is a single trailing clause that earns 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. Purpose, scope, ordering, and one alternative are all covered; only the relationship to adjacent tools like list_stream_decks and reorder_collections is left implicit.

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

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

Schema description coverage is 100% and the single streamDeckId parameter is documented in-schema as 'Deck ID from list_stream_decks'. The description only alludes to it via 'in a stream deck' and adds no format or sourcing 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?

States a specific verb (List), resource (custom collections), and scope (signed-in user's, within a stream deck, in display order). It also names the sibling get_collection so an agent can distinguish this list tool from the single-resource fetch 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?

Gives a clear use context (listing the signed-in user's collections in a given deck) and explicitly routes one case to get_collection. It stops short of stating when-not to use it (e.g., reorder_collections or the list_stream_decks prerequisite), so it 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds value by asserting no subscription is created and no charge occurs, which is a business-level side-effect guarantee annotations cannot express, though it omits pagination/result-size 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?

Three compact sentences: scope first, then routing to alternatives, then the negative side-effect statement. No redundant restatement of the title or schema content.

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 an output schema present, return values need no explanation, and the schema covers pagination via limit/nextToken. The description covers scope, alternatives, and non-effects, so an agent has what it needs; only pagination behavior is left entirely to 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?

Schema description coverage is 100% and the enum meanings for queryType and streamPackageCategory are fully documented in the schema itself. The description adds no parameter syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb (List), resource (stream packages), and scope (CREATED or SUBSCRIBED by the signed-in user), plus the extra payload (available prices). This clearly differentiates it from list_stream_packages (all packages) and the subscription-status 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?

Names both alternatives explicitly with their selection conditions: list_stream_packages for browsing all packages, get_stream_package_subscription for billing status. It also states a negative ('Does not create a subscription or charge the user'), leaving nothing 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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds one genuine behavioral fact beyond that — results come back in the user's saved display order — but says nothing about pagination, result size, or auth scope.

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 stating action, resource, scope, and ordering. Every clause carries information 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?

With an output schema present, return values need not be described, and annotations carry the safety profile, so the definition is close to sufficient. It could still note that the list is unfiltered/complete or point to reorder_stream_decks for changing the order, but no critical gap remains.

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 (additionalProperties: false), so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The schema is fully covered and the description correctly implies no filtering arguments exist.

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 (list), resource (stream decks), and scope (the signed-in user's), which cleanly separates it from get_stream_deck, create_stream_deck, and reorder_stream_decks. It does not explicitly name a sibling or state the boundary, but the plural/read semantics 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?

Usage is implied by 'the signed-in user's' (no user argument is needed/possible), but there is no explicit statement of when to reach for this versus get_stream_deck or reorder_stream_decks. An agent can infer the read-list case, but nothing 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavior: results are limited to the signed-in account, pagination state is preserved, and invitation state is not mutated. It stops short of stating auth prerequisites or page-size behavior, hence a 4 rather than 5.

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

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

Three short sentences, front-loaded with the core purpose, then behavior, then the exclusion. Every sentence earns its place and there is no filler.

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

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

With an output schema present, return values needn't be explained, and the description covers scope, pagination, and the mutation boundary. It does not say what an empty result implies or whether results are ordered, which are minor gaps for a two-parameter 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% and both parameters (limit, nextToken) are fully documented in the schema, so the description carries no burden here. It only alludes to pagination ('preserves pagination') without adding format or syntax beyond what the schema provides — baseline 3.

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

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

States a specific verb (List) plus a precisely scoped resource (pending stream invitations addressed to the signed-in account), and names the related sibling follow_stream so an agent can separate listing from consuming. The scope qualifiers ('pending', 'signed-in account') prevent confusion with the many other list_* 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?

Explicitly states the boundary — 'Does not accept or dismiss invitations' — and routes the agent to the correct alternative ('follow_stream can consume an eligible invitation'). That is a clear when-not-use plus a named alternative, which is exactly what the dimension asks 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 declare readOnly/idempotent/non-destructive, and the description adds real behavioral context: a linked account is required (unlike streams_all and search) and it does not create a subscription or charge the user. It omits pagination/return behavior, but the schema and output schema cover 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?

Three sentences, zero waste: purpose and ordering first, then the account prerequisite, then sibling routing and side-effect clarification. Every clause earns its place and the key facts are front-loaded.

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 browse tool with an output schema, the description supplies the remaining decision-relevant facts: auth prerequisite, sibling routing, and absence of side effects. Nothing needed to invoke 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% with descriptive fields for limit, nextToken, queryType, and streamPackageCategory, so the schema carries parameter meaning. The description only implies default ordering ('most-subscribed first') and adds no format detail beyond it, making 3 the appropriate baseline.

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 (browse) and resource (stream packages), defines what a package is ('bundles of streams sold as one subscription'), and notes ordering ('most-subscribed first'). It explicitly distinguishes itself from streams_all, search, and list_my_stream_packages, so an agent can pick 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 explicit routing: use this for the catalog, use streams_all/search when no linked account is needed, and use list_my_stream_packages for created or subscribed packages. Both when-to-use and when-not-to-use are covered with named 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results come back in display order and the saved layout configuration is serialized as JSON strings, which tells the agent what shape of payload to expect.

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 that front-loads the operation and scope, then appends the two return-format details. No filler, no 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?

With no parameters, an output schema present, and rich annotations, the description needs only to name the operation and hint at the payload. It does both, so an agent has everything required to call it 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?

The tool takes zero parameters, so per the rubric the baseline is 4; the schema is empty with 100% coverage and there is nothing for the description to clarify.

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 (List) and resource (terminal tabs), scoped to the signed-in user, and even characterizes the return (display order + layout config). It is clearly distinguishable from create/update/delete/reorder_terminal_tab by the 'List' verb, though it never names those siblings explicitly.

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

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

Usage is only implied by the name and description – an agent can infer this is the read-all operation for terminal tabs, but there is no explicit when-to-use statement and no routing away from reorder_terminal_tabs or get-style alternatives (there is no get_terminal_tab sibling, which partially limits the 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?

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), so the agent knows this is a repeatable state mutation. The description adds useful scope qualifiers ('every unread', 'signed-in account', 'in-app'), but does not explain that the change is irreversible or that no undo exists, which is exactly what the destructiveHint is flagging.

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, scope stated first and the disambiguation last. Every clause earns 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?

Output schema exists, so return values need not be described, and annotations cover the mutation/idempotency profile. For a zero-parameter bulk action, nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax the description could or should explain. The description correctly avoids inventing filters and reiterates the account-level scope instead.

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 ('mark ... as read') and resource ('every unread in-app notification in the signed-in account'), and explicitly names the sibling it differs from (mark_notification_read). An agent can distinguish bulk vs. single-target behavior 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?

Provides explicit routing: this tool for all notifications, with the alternative (mark_notification_read) named and the condition that selects it ('for one notification'). No inference required.

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, readOnlyHint=false, so the mutation safety profile is covered by structured data. The description adds a real behavioral constraint not in the annotations: foreign notification IDs are rejected, i.e. ownership/authorization is enforced. It does not add anything on idempotency or response behavior, but that is already structured.

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: action, constraint, alternative. Front-loaded action statement, zero filler, 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?

An output schema exists, so return values need not be explained. For a one-parameter mutation tool, the description covers the action, the ownership constraint, and the sibling alternative — nothing an agent needs 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 description coverage is 100% and the single parameter's description already points to its source ('id from get_notifications'), so the baseline is 3. The description restates ownership semantics for the ID but adds no syntax, format, or sourcing detail 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?

States a specific verb and resource ('Mark one of the signed-in user's notifications as read') and scopes it to the signed-in user's own notifications. It also names the sibling tool it is not, so an agent can distinguish it from mark_all_notifications_read 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?

Explicitly routes the agent to mark_all_notifications_read for the bulk case, and states the exclusion condition ('IDs that are not the signed-in user's notifications are rejected'). Both when-to-use and when-not-to-use are covered.

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 spelling out downstream consequences: removed targets stop appearing in stream reads, post searches, WebSocket delivery, and app feeds after reconnect, and cascade into collection sources (deleting sources left empty). It also discloses the target-allowance constraint, the format-match requirement, and the explicit non-guarantee ('does not purchase access or confirm that targets are collected').

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 core action and keeps every sentence load-bearing, but the paragraph is dense with long compound sentences that could be split or trimmed. Length is largely justified by the cascading destructive behavior, so it avoids padding.

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, subscription-gated mutation with an output schema and rich annotations, the description covers prerequisites, side effects, format constraints, and non-goals. Return values are correctly left to the output schema rather than re-explained.

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 add/remove/streamId thoroughly, setting a baseline of 3. The description adds genuine meaning by characterizing what targets are (accounts, channels, repositories, keywords) and pointing to get_stream for the required format, though it largely reiterates the schema's own retention and format notes.

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 (add or remove) on a specific resource (targets in the signed-in user's selection on a Synoptic custom-target stream) and clarifies it preserves the other targets, which distinguishes it from set_stream_custom_targets. An agent can tell what it does and what it doesn't replace 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 clear preconditions—requires following the stream and an active direct subscription—and the 'keeping other targets' phrasing implicitly routes to the set_ alternative. It never explicitly names a sibling tool or states when NOT to use it, so it stops short of full when-to-use/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?

Goes beyond the annotations by disclosing that publishing may notify users, that the returned state is authoritative, and that the action cannot be undone through MCP. This is meaningful context on side effects and irreversibility that the destructiveHint/idempotentHint flags alone don't convey, though it doesn't cover auth requirements or rate limits.

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

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

Three short sentences, front-loaded with the core action and state transition, then side effects, then the routing pointer. 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 an output schema present, return values need not be explained, and the annotations carry the safety profile; the description covers the remaining agent-critical facts (irreversibility, notifications, post prerequisite via schema). Only minor gaps remain, such as permission requirements for publishing.

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

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

Schema description coverage is 100% and the single 'id' parameter already documents that it must be a DRAFT stream you own with a post prerequisite. The description's 'owned draft stream' phrasing merely restates the schema, adding no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (publish) and resource (an owned draft stream) plus the resulting state change to ACTIVE. This is clearly distinguishable from create_stream, update_stream, and create_stream_post in the sibling list, and the 'owned draft' qualifier scopes it precisely.

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 one adjacent need ('Use create_stream_post to add posts') but never states when to publish versus when not to, nor what the caller must have done first (the schema, not the description, carries the 'needs at least one post' prerequisite). Usage 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds a useful clause: it does not modify the X account, which clarifies blast radius. It does not mention reversibility or side effects on the profile beyond this.

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 do the necessary work: the first specifies the target, the second prevents a likely misconception about affecting the X account. 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 zero-parameter destructive action with rich annotations and an output schema, the description covers the key facts. It could say more about what happens if the handle is absent, but is otherwise complete enough.

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 has no parameters, so the baseline is 4. The description does not need to explain any inputs and correctly focuses on the operation's effect.

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 (Remove) and resource (the verified X handle), with the precise scope: from the signed-in user's public Synoptic profile. The agent can tell what is being removed and from where without ambiguity.

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 clarifies what is being removed (the verified handle from the profile) but gives no explicit when-to-use guidance. There is no direct alternative to remove_x_handle in the sibling list, so the risk of misrouting is low, but no conditions or prerequisites are 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=false, destructiveHint=true and idempotentHint=true, so the mutation and reversibility profile is covered. The description's only added behavior note is the exhaustiveness constraint, which is largely duplicated in the sortOrder schema description; it does not spell out the consequence of omitting a collection (it is dropped from the deck).

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

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

Two tight sentences with the action front-loaded and zero filler. The second sentence partially duplicates the schema's sortOrder description, which keeps it from being a perfect 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 only two fully documented required parameters, a rich annotation set, and an output schema present, the description covers everything an agent needs to call the tool. The one gap is that the destructive side effect (collections not listed are removed) is only implied, leaving it to the annotations.

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 both parameters are documented, including where to source their values (list_collections, list_stream_decks). The description merely restates the sortOrder constraint, adding no syntax or format 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?

Names a specific verb ("Replace ... display order") and resource (a stream deck's collection ordering), so it is clearly distinct from the reorder_stream_decks and reorder_terminal_tabs siblings. It stops short of naming any alternative explicitly, so it is clear rather than 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?

The second sentence supplies a real precondition for correct invocation (every existing collection ID, exactly once), which implies list_collections must be called first. However, it never says when to choose this tool over another ordering tool or what happens if the precondition is violated.

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 readOnlyHint=false, so safety and repeatability are covered. The description adds the genuinely useful behavioral fact that this is a full overwrite of display order rather than an incremental move, plus the completeness requirement on the ID list.

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, and the core action ('Replace ... display order') is front-loaded before the constraint.

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?

An output schema exists so return values need not be explained, and the single parameter is fully documented. The only unaddressed question is what happens to decks omitted from the list, which matters given destructiveHint=true — a small but real 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% and the sortOrder description already states 'Every deck ID from list_stream_decks exactly once, in the new display order'. The description restates that constraint without adding format, ordering, or error-handling 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 ('Replace the signed-in user's stream deck display order'), which is unambiguous against siblings like reorder_collections and reorder_terminal_tabs, whose resources differ. It does not explicitly name those siblings, but the resource noun is distinct enough that no differentiation is strictly required.

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 instruction 'Include every existing deck ID exactly once' is a meaningful usage constraint, but the description never states when to reach for this tool versus update_stream_deck (the sibling for changing a deck's properties) or where the IDs come from. Usage 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description reinforces this by saying 'Replace' and requiring every existing tab ID exactly once, which warns the agent that omitted tabs are effectively dropped. It stops short of describing permissions or the response.

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, the action front-loaded and the completeness constraint immediately after. 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?

An output schema exists so return values need no explanation, and the destructive/idempotent profile is covered by annotations plus the 'Replace' wording. The definition is adequate for a single-array-parameter mutation, with only per-tab versus bulk routing left implicit.

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

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

Schema description coverage is 100% and the sortOrder description already specifies 'Every tab ID from list_terminal_tabs exactly once, in the new display order.' The description restates that constraint without adding format or ordering details 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?

States a specific verb (Replace) and resource (terminal tab display order) scoped to the signed-in user, distinguishing it from update_terminal_tab which modifies a single tab. It does not name list_terminal_tabs as the source of IDs, but the schema does.

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 implies usage (a wholesale reorder rather than per-tab edits) and gives the correctness constraint of including every tab ID exactly once, but never states when to prefer this over update_terminal_tab or list_terminal_tabs.

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-idempotent, open-world, non-read-only behavior; the description adds the consequential detail that each call creates a NEW request and must not be auto-retried on an uncertain result — exactly the information an agent needs when idempotentHint=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?

Four tight sentences, front-loaded with the action, then constraints, then retry behavior. No filler and every clause carries a distinct fact.

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

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

An output schema exists so return values need not be restated, yet the description still notes a confirmed ticket ID is returned. Combined with the mutation, retry and scope caveats, an agent has everything needed to invoke this 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 0%, so the description must carry parameter meaning. It adds content guidance for the description field (problem, proposed behavior, use case) but says nothing about the title field or the length limits, leaving one of two parameters undocumented.

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 ('Submit a feature request to Synoptic support') plus scope ('on behalf of the signed-in user'). It also explicitly negatives what the tool is not ('does not implement a feature'), which cleanly separates it from the create_*/update_* 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?

Gives clear when-to-use content guidance (describe the problem, proposed behavior, use case) and a strong when-not statement ('does not implement a feature or guarantee delivery'), plus an operational exclusion ('do not automatically retry an uncertain result'). It doesn't name a sibling alternative, but the other request_* tools serve unrelated resources rather than being substitutes.

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 declare non-idempotent, open-world, non-destructive, but the description adds what they cannot: the call returns a support ticket ID, guarantees no delivery, and — critically — that each call opens a NEW request so uncertain results must not be retried. That is exactly the behavioral context an agent needs for an irreversible open-world 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, then return semantics, then the retry warning. No filler. Slightly dense but every clause earns 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?

An output schema exists so return values needn't be explained, yet the description still signals the ticket-ID response. Combined with the non-retry warning and the 'does not create a stream' caveat, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0% and parameters are undocumented, so the description must compensate. 'Describe the source or website, desired content and use case' meaningfully guides what belongs in title/description, though it does not map guidance to each parameter by name.

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: 'Submit a stream request to Synoptic support on behalf of the signed-in user.' It also preemptively distinguishes itself from create_stream by clarifying it 'does not create a stream', which is exactly the ambiguity a sibling-heavy catalog creates.

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 (requesting a stream from support) and implicitly routes away from create_stream by stating it does not create one. It stops short of explicitly naming create_stream or request_feature as alternatives, so it lacks the full when/when-not routing 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?

Beyond annotations, the description discloses the concrete side effect ('Sets terminalAccessRequested, which get_me reports'), confirms idempotency in plain language ('repeating the call changes nothing'), and rules out common misconceptions (no access granted, no support ticket, no trades). This adds significant behavioral context that annotations 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?

The description is three tight sentences, front-loading the core action and then adding side-effect, idempotency, limitation, and alternative information. Every sentence earns its place with no 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 a no-parameter, idempotent request action with annotations and an output schema, the description covers purpose, side effect, idempotency, non-effects, and the sibling alternative. 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?

The tool has zero parameters, so there is no parameter syntax or semantics to explain. The baseline for a 0-parameter tool is 4, and the description appropriately does not waste words on nonexistent inputs.

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 uses a specific verb and resource: 'Join the waitlist for early access to the Synoptic trading terminal (beta) for the signed-in account.' It also distinguishes itself from the sibling request_feature by explicitly naming it for other product requests, so an agent can tell them apart without opening schemas.

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 names the alternative tool for other product requests ('Use request_feature for other product requests') and clarifies what this tool does not do ('Does not grant access, open a support ticket or place trades'), giving clear when-to-use and when-not-to-expect 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 readOnly/openWorld annotations by disclosing visibility rules (public streams without sign-in; private streams only for owners, followers, subscribers, invitees) and a non-obvious ordering caveat ('ordered by follower count, not relevance'). It also names the returned fields, which is genuinely useful behavioral context.

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 purpose, then layers match scope, visibility, ordering, and return fields, with the get_stream pointer last. Every sentence carries information, though it is denser than strictly necessary for a search tool.

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?

Despite an existing output schema, the description still names the key returned fields, and it fully covers matching scope, visibility, ordering, and the follow-up tool. Nothing needed to invoke or interpret a call 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 limit, offset, and the query semantics are already fully documented in the schema. The description's matching-scope sentence largely mirrors the query parameter's own description and adds no new parameter detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search the Synoptic stream catalog by keyword') and immediately scopes what is matched. It distinguishes itself from the sibling search_stream_posts by explicitly declaring it does 'not search post text', so an agent can route correctly 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?

Gives a clear next-step alternative: 'Use get_stream to inspect a result before reading posts or configuring targets', which tells the agent when this tool ends and another begins. It also implicitly excludes post search, but never names search_stream_posts explicitly as the alternative, leaving that 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 declare readOnly, non-destructive, closed-world, so the safety bar is low. The description still adds real behavioral context: results are newest-first, custom-target restrictions apply, and pagination uses nextOffset rather than the opaque history tokens used elsewhere. It stops short of describing rate limits or result-shape behavior, but that is largely covered by the output 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 tight sentences with the core action front-loaded, then pagination guidance, then sibling routing. Every sentence earns place, though the final clause 'the search tool finds streams, not posts' is slightly compression-heavy and takes a re-read to parse.

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 an output schema present, return values need not be described, and the description covers ordering, scoping, access restrictions, and pagination semantics. It is close to complete; only edge behavior (empty results, escaping in text queries) is left implicit.

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

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

Schema description coverage is 100%, so the schema already documents streamId, text syntax, limit, offset, and the ISO date bounds. The description reinforces ISO date bounds and the nextOffset contract but adds little syntax or format meaning beyond the schema, so the baseline 3 is correct.