Connections

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description adds substantial behavioral detail: two row kinds (normal vs brokered), the `via` and `callWith` fields, and the critical caveat that Stripe can appear both ways with different semantics. It also discloses the incompleteness risk from brokeredUnavailable, far exceeding what annotations 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 long but every sentence earns its place. It is front-loaded with the core purpose and filters, then logically progresses to usage with connections_execute and the nuanced brokered/Stripe handling. The structure guides the agent from high-level to edge cases without 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?

Despite lacking an output schema, the description enumerates expected fields (service, instance, accountId, region) and introduces `kind`, `via`, `callWith`, and `brokeredUnavailable`. It also explains how to consume the result for targeting connections_execute, making the tool fully actionable for an agent.

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

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

Schema description coverage is 100%, so both parameters are documented. The description adds meaning by explaining how `match` narrows (e.g., instance names follow `<plane>@connections.icu`) and that `service` filters by slug. It also clarifies the combination of filters, going beyond the schema's basic descriptions.

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 (list) and resource (connected accounts/instances) with clear scope: 'every connected account/instance this company has'. It distinguishes itself from siblings by explicitly routing usage to connections_execute and clarifying that Stripe brokered rows are handled via Pay endpoints, not this 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?

Provides explicit when-to-use ('THE answer to is <service> connected?') and how-to-filter guidance with `service` and `match`. It also gives exclusions: brokered Stripe accounts should use Pay endpoints, and warns that brokeredUnavailable means the list is incomplete, so it must not be read as 'not connected'.

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, destructiveHint=false and openWorldHint=false, so the added 'Read-only, no side effects' line is partly redundant. What is genuinely additive is the disclosure that install_url is null for coming_soon add-ons and that the `say` field is a ready-to-relay sentence, which tells the agent how to behave on edge cases rather than just what data comes back.

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

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

Three sentences that are front-loaded with the payload (what is returned) before the edge-case handling and the read-only reassurance. Dense with information and free of filler, though the closing 'Read-only, no side effects' repeats the annotations.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the returned fields and explaining the two special ones (`say`, null install_url). For a zero-parameter, read-only lookup with annotations covering safety, nothing needed to invoke or relay 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 schema has nothing to document and the baseline of 4 applies. The description correctly says nothing about inputs instead of padding with irrelevant argument talk.

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 exactly what is returned: Chrome add-ons for Connections Email, Schedule and Notes, with per-add-on name, browser, status, install_url, summary and highlights. That distinguishes it cleanly from the many sibling tools (email_get, calendar_list, etc.). It is descriptive rather than verb-led, but the resource and scope 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?

It establishes the context of use ('What Connections offers outside this chat') and gives a concrete conditional handling rule for install_url being null (status coming_soon) plus a 'never invent a store link' guardrail. It does not name sibling alternatives or explicit when-not-to-call conditions, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the bar is lower; the description adds real context beyond them — the event is private to the member, exactly one event is created, and the reply should be read back to the member. It does not explain that repeated calls create duplicates (idempotentHint=false) or what the destructive hint means for a pure-add operation, which are the remaining gaps.

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?

Well front-loaded: the trigger conditions come first, then behavior, then defaults, then alternatives. The quoted example phrases are bulky but functional; the description runs long for a four-parameter tool, though each sentence carries routing or behavioral weight.

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

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

There is no output schema, and the description compensates by describing what the reply contains and instructing the agent to say it back. Combined with the privacy scope, the defaults, and explicit sibling routing, 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 100%, so title, starts_at, ends_at and all_day are already documented with defaults and format. The description restates the same facts (UTC offset example, one-hour default, all_day meaning) rather than adding new semantics, 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 precise verb+resource ('Creates ONE event on the member's own Connections calendar') and immediately delimits scope as the private, member-only calendar. It also names the two nearest siblings it is not (connections_event_create, connections_todo_add), 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?

The opening sentence enumerates the triggering phrasings ('add it to my calendar', 'block out 2-4pm tomorrow') and the closing sentence gives explicit when-not routing: public event with page/tickets/RSVPs → connections_event_create, to-do with no time slot → connections_todo_add. Both the selection and exclusion conditions 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 signal readOnlyHint and non-destructive behavior. The description adds meaningful context: it returns events from multiple sources, lists the returned fields, orders events 'soonest first,' and instructs the agent to answer from this list rather than chat history. It does not mention absence/pagination behavior, but that is a minor gap given the 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?

The description is longer than average but front-loads the primary use case, then delivers return shape and window behavior in dense, information-packed sentences. Every sentence contributes value 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?

There is no output schema, but the description enumerates the returned fields (id, title, starts_at, ends_at, all_day, source), the ordering, the window semantics, and the data sources. It also tells the agent to prefer this list over chat history. For a read-only list tool with two optional parameters, nothing essential 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% and both parameters are already described with types and defaults. The description restates the window semantics ('default 7, at most 62') but adds little beyond what the schema provides, 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?

The description opens with a specific verb and resource: 'Use this when the member asks what is on their calendar or schedule' and identifies the resource as 'the member's own Connections calendar.' It further distinguishes itself from siblings by listing aggregated sources such as hosted events, note deadlines, and connected Google Calendar.

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 enumerates trigger phrasings: 'what is on their calendar or schedule, whether they are free or busy... today, tomorrow or this week, or when something on their calendar is.' It does not explicitly name alternative tools or when-not conditions, but the trigger list is clear enough for routing.

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

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

The description goes beyond the basic annotations (readOnlyHint=false, destructiveHint=true) by detailing the irreversible nature of the claim: allowed exactly once, locked afterward, and that changing/clearing is Studio-only. It also explicitly notes that no unclaim/swap tool exists, giving the agent a clear understanding of the long-term consequences. This fully discloses the mutating and potentially destructive behavior.

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

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

The description is somewhat verbose but every sentence carries crucial information (unassigned condition, once-only rule, human confirmation, lock, Studio-only override, no unclaim, parameter source). It is front-loaded with the purpose and then explains constraints. A slightly tighter phrasing could reduce redundancy, but the length is justified given the number of important caveats.

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 description fully equips an agent to decide when to use the tool and what to expect: it covers the target state (unassigned), the mutation (binding), the restriction (once, locked), the source for the parameter, and the downstream limitation (Studio-only changes). There is no output schema, but the tool returns a confirmation or error implicitly, and that is sufficient. No critical context 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 schema already defines `company` as a required string, and the description adds that it can be either a companyId from connections_list_companies or an exact company name. This enriches the schema by providing a format/source, but it does not clarify edge cases like case sensitivity or behavior when an exact name matches multiple companies. Still, it covers the essential semantics beyond the raw schema.

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

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

The description clearly states the exact action ('bind this UNASSIGNED registration to a company') and immediately distinguishes it from siblings by emphasizing the one-time, unassigned-only nature. It also cross-references connections_list_companies, eliminating ambiguity about which tool to use for listing companies. This is a precise verb+resource+constraint specification.

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

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

The description explicitly defines when the tool should be used ('only while no company is assigned'), states the prerequisite of confirming with a human, and warns about the post-claim lock and the absence of an unclaim/swap tool. It also provides a direct pointer to connections_list_companies for obtaining a valid companyId, offering complete actionable guidance without needing to inspect other tools.

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 discloses that the link is single-use with a 10-minute expiry, that credentials land in the company vault via provider callback (not via conversation), and that a 409 error occurs if the service already has live connections. It also notes the human must be signed in to the provider. These details go beyond the annotations, which only indicate destructive and open-world hints, and do not contradict them.

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 long but information-dense, front-loading the core purpose and then systematically addressing parameter usage, error handling, and human requirements. It is well-structured with clear conditionals, though it could be slightly more concise without losing critical details.

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 complex OAuth tool with 7 parameters and no output schema, the description is remarkably complete: it covers the primary use case, the reconnect/re-consent flow, the 409 error response, the return fields (url, expiresAt), and the requirement for human sign-in. An agent has everything needed to invoke the tool 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 description adds significant context to the parameters: it explains the role of reconnectId vs instanceName (with precedence), the newConnection flag's purpose, and the install/directory specifics for Microsoft. While the schema already describes each parameter, the description clarifies the semantic relationships and error scenarios, enhancing the agent's understanding.

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 explicitly states the tool 'Mint the provider's authorize URL for an OAuth connector' and explains the purpose: enabling a human to connect or reconnect via a one-click link. It clearly differentiates from sibling tools by focusing on OAuth link generation, which is unique 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?

The description provides explicit conditions: when to pass reconnectId or instanceName for re-consent, when to pass newConnection:true to add another account, and what happens when neither is passed (409 with a list). It also clarifies the precedence between reconnectId and instanceName, giving clear guidance for parameter selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: it returns every field on the contact record, includes recent relationship touches by default, and explains that include_timeline=false skips a second read. No contradiction with 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?

The description is well-structured and front-loaded with the primary use case, then proceeds to the required parameter and return behavior. Every sentence contributes useful information, with no filler or repetition of schema details beyond what 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?

The description is complete for a read-only detail tool: it explains when to use it, where to get the required id, what fields are returned, and how the optional timeline parameter affects behavior. Since there is no output schema, the description appropriately compensates by describing the return payload.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important semantic context beyond the schema: it identifies where the `id` value comes from (connections_contacts_list), clarifies that timeline data is fetched by default, and explains the purpose of include_timeline. This helps the agent use the parameters correctly.

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 action (get details for one specific contact) and resource (contact record), and explicitly distinguishes it from the list sibling by requiring an `id` from connections_contacts_list. It clearly communicates what the tool returns: full contact fields plus recent touches.

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

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

The description gives explicit when-to-use guidance ('when the member asks for details about one specific contact') and tells the agent to pass the `id` from connections_contacts_list. It does not explicitly contrast with connections_contacts_list beyond that, but the usage context is clear enough for an agent to select this tool over its sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond them: results are the member's own contacts, ordering is newest-updated first, and query words are scored rather than required together. It stops short of discussing pagination behavior or result-size implications, keeping it at a 4.

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 usage trigger before the return and parameter notes. Dense but every clause carries information; minor redundancy between the description and the rich schema keeps it from a 5.

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

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

Though there is no output schema, the description enumerates the compact return shape (name, email, phone, company, job title, tags, needs_follow_up) and ordering, and covers the main filter options. Combined with 100% schema coverage, 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 description coverage is 100%, so the baseline is 3. The description reinforces a couple of the key parameters (query, needs_follow_up: true) but adds little the schema does not already state in more detail, so it does not exceed the 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 and resource (list the member's own Connections contacts) and enumerates the returned fields, so an agent knows exactly what this returns. It also distinguishes itself from the sibling connections_contacts_get for single-record retrieval, so it is identifiable without opening another 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?

Opens with an explicit when-to-use trigger list ('member asks about their contacts, who they know, their network, people they have met, or who needs following up') and routes the agent to connections_contacts_get {id} for the single-contact case. The alternative and its selecting condition are both named.

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

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

Adds substantial context beyond the annotations: it writes only to the member's own contacts (consistent with openWorldHint=false), appends exactly one note dated now unless occurred_at is supplied, returns the recorded touch, and silently writes nothing but returns candidates on an ambiguous name. The destructiveHint=true flag is not echoed, but the appending-write semantics and blast radius are disclosed.

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

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

Front-loaded with the trigger scenario before mechanics, and every sentence carries information (trigger, parameter routing, write behavior, ambiguity semantics, scope). It is dense and slightly long, but nothing is filler or redundant with the schema.

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

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

With no output schema, the description usefully covers the return value ('returns the recorded touch') and the degenerate return (candidate list on ambiguous names), and with six parameters it explains how to supply the identifying ones. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so baseline is 3, but the description adds selection logic the schema doesn't: prefer `id` from connections_contacts_list, fall back to `name`, and use `email` only to disambiguate same-name contacts. It doesn't restate enum values or the 4000-char note limit.

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 ('Log a note or touch on one of the member's contacts') with concrete example utterances, and distinguishes itself from the read-side siblings (connections_contacts_get / connections_contacts_list) and from connections_note_save by naming the target record. 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 the exact trigger condition ('when the member says they talked to, met or called someone and wants it kept on that person's record') plus two paraphrased user utterances. It also states the resolution path when only a name is known and the required contacts:write scope, so usage 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 declare destructiveHint=true and readOnlyHint=false; the description adds crucial context — the copy shares the credential, no secret is duplicated or returned, and overwrite replaces a dead/duplicate row in a single act. Also discloses error codes and their meaning, which goes well 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?

Dense but front-loaded: purpose first, then constraints, then parameter rules, then return shape. A few clauses (e.g. the error-code enumeration) could be trimmed, but each earns its place given the tool's complexity.

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

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

Covers preconditions, safety profile, parameter selection rules, error recovery, the sibling hand-off, and the return shape {connectionId, projectId, instanceName, sharesCredential}. For a destructive, open-world mutation tool with no output schema, this is complete.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real semantic constraints: exactly one naming form (connectionId XOR service+instance), the resulting error codes (conflicting_source, missing_source, ambiguous_source), and overwrite's target-workspace scoping. It earns above 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 precise verb+resource+scope: copy a connected service from one of the member's workspaces into another, sharing the same credential. Distinguishes clearly from connections_copy_connection_link, which it names as the alternative for user-initiated copies.

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

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

Explicit preconditions (cross-workspace access ON, both workspaces solely owned), explicit routing to connections_copy_connection_link when the member asked, and explicit do-not-retry on cross_workspace_refused. Also gives guidance on when to pass fromProject and how to recover from not_found/ambiguous_source.

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 declare destructiveHint=true and readOnlyHint=false, but the description explains that nothing is copied by the call itself, that the agent cannot confirm it, that the member must tap Confirm in Studio, and that the link is single-use, account-bound, and expires in 10 minutes. This resolves the apparent tension between the safe mint step and the destructive downstream action the flagged annotations imply.

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 compact sentences, front-loaded with what the tool does and when to use it, then the behavioral constraints. Every sentence carries distinct, non-redundant information, including the return shape.

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

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

With no output schema available, the description compensates by naming the return payload ({url, expiresAt}), plus the lifetime, single-use, account-scope, and both-workspaces-ownership constraints. For a tool whose execution defers a real mutation to the member, this covers everything an agent needs to call and then handle the result.

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

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

Schema description coverage is 100%, so connectionId, toProject, instanceName and the mode enum are already documented in the schema. The description restates the copy-vs-move semantics that the mode enum encodes ('copies (or moves)') but adds no format, default, or validation detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Mint a one-tap link that copies (or moves) one connected service from one of the member's workspaces into another') and frames the fallback relationship to the sibling connections_copy_connection via the cross_workspace_refused condition. An agent can distinguish this from connections_copy_connection and the other connections_* tools 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 an explicit trigger ('for when the member asked you to do it and connections_copy_connection returns cross_workspace_refused') and a precondition ('Both workspaces must be the member's own'). It names the alternative tool and the exact condition that routes to this one, 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?

With annotations present the bar is lower, and the description still adds real behavioral context: default action, the ask/done status protocol and return shape (outcome, path, people, tools, brief), versioning semantics ('Every version is kept'), the stale_version conflict response tied to base_version, and the list of edit ops. The one gap is that save 'replaces the whole graph' while destructiveHint is false — the versioning/revert story justifies that, so I do not treat it as a contradiction.

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

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

Front-loaded with purpose and the default action, and most sentences do carry action-specific meaning. But 11 actions are compressed into a single unbroken paragraph of run-on clauses, and a bulleted per-action structure would have made the routing far easier to scan. Several clauses are also compressed to the point of ambiguity ('turns stores one ledger row per chat turn from a PC's hook').

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 tool with 18 parameters, nested objects, 11 actions and no output schema, the description covers the necessary ground: what each action does, the default, the conflict behavior, and the shape of responses for the main read actions. It is close to complete, though a couple of actions (turns input contract, find's return ordering) are only thinly described.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by partitioning the 18 parameters across the 11 actions (chat for run/log/brief, ops/why/base_version for edit/save/revert, facts/answers for run, rows for turns, query/limit for find). The one thing it does not add is the syntax of the answers/facts objects beyond the schema's own examples.

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 concrete resource (the workspace's decision flowchart / CrAInium flow) and enumerates all 11 actions with distinct verbs (walk, list, find, get, edit, save, revert, history, log, brief, store). It is clearly distinguishable from siblings such as connections_execute or connections_notes_search. However, the core identity is embedded in a dense wall of text rather than front-loaded as a single clear statement.

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

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

It gives a strong when-to-use trigger ('when an AI chat starts a task and needs to know how to do it'), states that run is the default, and even implies exclusions ('head lists the flowchart's quick exits... so those need no call'). It does not compare itself to any sibling tool or state when this tool should be avoided in favor of another, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces this with 'Read-only, cheap, no side effects.' The description adds valuable behavioral context beyond annotations: the setting can only be changed by the member in Studio settings, the reply carries a link to send them, and shared workspaces are never covered. It doesn't describe the exact response shape, but with no output schema and annotations covering safety, this is strong. Minor deduction for not detailing the response fields beyond 'enabled' and the link.

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 dense but every sentence earns its place: purpose, when to call, conditional behavior, exception for shared workspaces, and a closing safety note. It is front-loaded with the core question and immediately gives the action rule. No fluff 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?

For a zero-parameter, read-only check tool, the description is complete. It covers the decision logic, the exception case, the limitation (only member can change), and the follow-up action (send the link). The sibling list shows many action-oriented tools, and this description fully equips an agent to decide when to call this check versus just acting.

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 the schema is trivially complete (100% coverage). The description adds meaning by explaining what the response's `enabled` field means and how to act on it, which is more than the empty schema provides. Baseline for 0 params is 4, and the description earns it by interpreting the key output field.

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 clearly states the tool's purpose: to check whether the account has granted permission to work across all solely-owned workspaces without asking. It uses a specific verb ('check'/'call it before') and resource ('cross-workspace access'), and distinguishes it from sibling tools by framing it as a pre-flight authorization check rather than an 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?

The description provides explicit when-to-use guidance: 'CALL IT BEFORE you ask the member to confirm any cross-workspace act' and lists concrete examples (creating a workspace, copying/moving a connected service, switching connections). It also gives clear conditional behavior: if enabled, proceed without asking; if false, ask first. It even specifies an exclusion: shared workspaces are never covered, always ask. This is exemplary usage 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 declare the safety profile (not read-only, destructive, non-idempotent, open world). The description adds substantial behavior the annotations cannot carry: publish defaults to live and requires title plus full_description, drafts save on any plan, live listings need a paid plan and fail with an explanatory reply rather than creating anything, public listings are visible to everyone, and dry_run previews without side effects.

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 trigger phrase and then the publish/plan/dry-run semantics in tightly packed sentences. It is slightly dense at six sentences, but each carries distinct constraints rather than 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 13-parameter, non-idempotent mutation tool with no output schema, the description covers the essential gaps: default publish behavior, the live-listing paywall and its failure mode, draft fallback, visibility implications, and a dry_run escape hatch. An agent has what it needs 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%, so a 3 is the baseline, but the description adds genuine cross-parameter meaning: publish only goes live when title and full_description are both present, and visibility/password/publish interact with the plan gating. It stops short of explaining region/category findability beyond what the schema already says.

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

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

States a specific verb and resource (creates one deal on Deals) and enumerates the member intents that trigger it (post a deal, list a raise, sell a business, find a partner/buyer/investor), which cleanly separates it from the read-only sibling connections_deals_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?

Gives explicit when-to-use triggers tied to user phrasing and explains the publish-true vs publish-false branch. It does not name a sibling alternative (e.g. connections_deals_list for browsing deals), so the routing guidance is clear 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 a safe read (readOnlyHint true, destructiveHint false). The description adds real context beyond that: the feed is 'always active, public listings', 'mine' includes every status including drafts, and the feed ranks a query by relevance. It stops short of describing pagination behavior, but the safety profile is already covered structurally.

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 trigger conditions, then scope semantics, then filters, then the alternative tool. Well-organized and mostly tight, though the row-field enumeration slightly overlaps with schema-documented outputs.

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

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

With no output schema, the description usefully enumerates what each row carries (title, summary, category, region, capital sought, status, link) and covers both scopes plus the posting 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%, so the schema already documents limit, query, scope, detail, fields, offset, region, status and category with defaults and enums. The description reaffirms scope semantics and filtering but adds little syntax the schema lacks, 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/browse) and resource (deals/listings), enumerates the trigger phrasings, and distinguishes the two scopes ('feed' vs 'mine'). It also names the sibling connections_deal_create as the posting alternative, so an agent can separate it from nearby tools.

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

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

Explicitly says when to use it ('when the member asks about Deals, listings, what is for sale, raises, or their own postings') and routes the write case to connections_deal_create ('To post a new deal, use...'). 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 readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: it returns one workspace-sent message with a full timeline of delivered, opened, clicked, bounced, and complained events, and requires an id from prior send/list calls.

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 two sentences, front-loaded with the usage trigger, and contains no filler. Every sentence contributes either the when-to-use condition or the return behavior.

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 simple: one required parameter, no output schema, and read-only annotations. The description fully covers what the agent needs: when to call it, what identifier to pass, and what the response contains.

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 schema covers the single 'id' parameter fully, so the baseline is 3. The description adds extra value by clarifying that the id comes specifically from connections_email_send or connections_emails_list and that it refers to a message this workspace sent.

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 ('look up' / 'Returns') with a clear resource: one sent email and its event timeline. It distinguishes itself from send/list siblings by focusing on retrieval of a single message's delivery outcomes.

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

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

The description explicitly says 'Use this when the member asks whether an email arrived, bounced, was opened or clicked,' giving a clear trigger condition. It does not explicitly contrast with alternatives, but it references that the id comes from connections_email_send or connections_emails_list, which is helpful routing context.

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

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

Annotations already declare destructive=true and openWorld=true, but the description goes well beyond them: messages 'cannot be recalled', they land in the recipient's inbox, the sender must be on a connected+verified domain, and failures return a named reason (suppressed recipient, unverified domain, spent daily ceiling, no credits). That is exactly the operational context an agent needs before firing an irreversible send.

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

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

Three tightly packed sentences: trigger first, then irreversibility plus the dry-run escape hatch, then failure modes, then sibling routing. Every clause carries information and nothing is repeated from 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?

For a 17-parameter, nested-object, destructive tool with no output schema, the description covers the risky and ambiguous parts (irreversibility, verification prerequisite, error taxonomy, scheduling semantics are in the schema). The one gap is what a successful call returns — no output schema exists, so a phrase about the success payload (message id / status / scheduled confirmation) would close the loop.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that dry_run:true returns the exact message without sending and by tying the `from` parameter to the verified-domain requirement. The idempotency_key note ('returns the first result instead of sending again') is consistent with a default idempotentHint of false rather than contradicting it, since idempotency only holds when the key is supplied.

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 ('send or email someone from their own business domain') with the product name (Connections Send) and scope ('ONE real message, now or at a scheduled time'). It clearly separates itself from the read-side siblings connections_email_get and connections_emails_list, which it names 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 trigger condition is stated up front ('when the member asks to send or email someone'), and the routing to alternatives for other intents is explicit: connections_email_get to check status, connections_emails_list to see what went out. It also names dry_run:true as the non-sending preview path, so the agent knows when not to actually send.

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?

Given that readOnlyHint=true and destructiveHint=false already cover the safety profile, the description adds genuinely useful behavioral context: results are 'newest first,' the outcome filter separates delivered from non-delivered mail, and each row contains id, sender, recipients, subject, outcome, and timestamp. This is beyond what annotations provide and helps the agent set expectations.

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 entire description is two sentences with zero fluff. Use cases are front-loaded in the first sentence; ordering, filter semantics, and output fields are in the second. Every phrase 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?

For a tool with three optional parameters and no output schema, the description is complete: it states scope (workspace emails), ordering, filtering semantics, and row contents. It does not explain pagination via `before` or the default `limit`, but those are documented in the input schema, so the description's job is largely done.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value by explaining the outcome filter's meaning and that accepted means handed to the mail system while the others did not go out (or are scheduled). This clarifies the enum values beyond the schema's own descriptions, lifting the score to 4.

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

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

The description opens with specific use cases ('what emails they sent, what went out recently, or which sends did not go out or are still scheduled') and clearly identifies the resource (emails in the member's workspace). It distinguishes itself from the sibling connections_email_get by noting that each row carries an id for that tool, so the agent can tell list from get.

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 provides explicit when-to-use scenarios and clarifies how the outcome filter should be interpreted ('accepted = handed to the mail system; the others are sends that did not go out'). It does not explicitly say 'use connections_email_get for a single email' or state when not to use this tool, but the pointer to the id for email_get is a useful routing hint.

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

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

Beyond the annotations (which only flag non-read-only, destructive, non-idempotent), the description discloses that the event is created as a private draft until published, that it has no side effect on the member's calendar, and prescribes a dry_run-first workflow. These are substantive behavioral facts an agent could not infer from the annotation set.

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 trigger condition and the core behavior, and every clause (draft state, calendar exclusion, dry_run, config routing) carries distinct information. It is dense and slightly long, but no sentence is wasted.

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

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

For a mutation tool with no output schema, the description covers what gets created, its draft/privacy state, the alternative tool for scheduling, the dry_run safeguard, and where downstream edits live. 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%, so the baseline is 3, but the description adds real value for dry_run by instructing the agent to run it first and surface the result to the member before writing. It does not add syntax detail for the other seven params, which the schema already covers.

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

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

The description states a specific verb and resource ('Creates ONE hosted event... its own public page with RSVPs and tickets') and immediately differentiates from the calendar sibling. An agent can distinguish this from connections_calendar_add and connections_events_list 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 trigger phrasing ('host an event', 'set up a meetup'), an explicit exclusion ('for add it to my calendar, a meeting, an appointment or blocked-out time, use connections_calendar_add'), and routes all remaining configuration to events_manage_hosted_events. When-to-use, when-not, and the alternative are all named.

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 readOnlyHint and destructiveHint, so the description's job is to add behavioral context. It does: it explains the default filtering (unfinished events, soonest first), the fields returned (date, location, public link), and the cross-workspace fallback (names the other workspace and reconnection page). This goes beyond the structured annotations to give the agent a complete behavioral model.

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

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

The description is a single paragraph but is information-dense. It front-loads the usage guidance and provides the return format and edge-case behavior without fluff. While not broken into sections, it is still efficient and each 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?

Given the tool has 6 parameters but no output schema, the description adequately covers the tool's context: it explains the main use case, the alternative, the default sorting/filtering, the returned fields, and the cross-workspace edge case. An agent has enough information to invoke the tool correctly in the intended scenario.

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 each parameter is already documented. The description reinforces the default behavior (unfinished, soonest first) which maps to the 'upcoming' parameter, but it does not add syntax details or examples beyond the schema. Per calibration, a baseline of 3 is appropriate when the schema carries the full parameter burden.

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

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

The description clearly states the tool's purpose: it lists events the member hosts (upcoming, hosted), and directly distinguishes it from connections_calendar_list (their own calendar). It also specifies the returned data (date, location, public link). This is a specific verb-resource pairing with clear sibling differentiation.

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 begins with an explicit when-to-use directive ('Use this when the member asks about the events they host...') and provides a direct alternative ('for what is on their own calendar, use connections_calendar_list'). It also explains the fallback behavior when the workspace holds none of the member's events, giving clear guidance on expected behavior in edge cases.

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 a coarse destructive/openWorld profile; the description adds what actually happens: third-party calls use vault credentials attached server-side, first-party endpoints run as the signed-in member, the ~24s workflow budget stops before starting a new step and returns ok:false/partial:true with a resume instruction, and outputFilter misses report outputFilterMatched:false with a bounded snippet. This is exactly the behavioral 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?

Purpose and the key restrictions are front-loaded, but the body is a single dense paragraph that packs catalog execution, workflows, instance targeting, five fast-path ops and three AWS shaping flags together. Much is necessary for this tool's breadth, yet headings or bullets would make it far more scannable, and several clauses are redundant with schema text.

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 tool this broad with 7 params, a 100%-covered nested schema and no output schema, the description covers the modes (endpoint, workflow, fast-path ops), their constraints, credential behavior and partial-failure semantics. Nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the endpoint_id-vs-service+tool_name selection logic and documents workflow step reference syntax ({{params.x}}, {{steps.<id>.<path>}}). Some content (outputFilter JMESPath example, paginateAll caps, includeEnv) largely restates schema descriptions, keeping it below 5.

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

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

States a specific verb+resource: 'Run ONE endpoint of the Connections operator catalog by endpoint_id (or service+tool_name) with its params.' It distinguishes itself from siblings by naming connections_search_catalog (source of endpoint_id) and connections_accounts (source of instance), so an agent can tell it 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?

Explicit routing rules: use endpoint_id when you have one from a search, service+tool_name when you know the op by name, and the alternative workflow path for multi-step chains. It also states a hard when-not: money-moving payment-provider operations (refunds, payouts, balance transfers, charges, captures) return an error pointing to the dashboard, while other writes still run here.

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, but the description adds substantial behavioral context beyond them: connected endpoints are searchable and unconnected ones are not 'by design', the copy-it-yourself vs hand-over-link decision depends on cross_workspace_access state, and the hard constraint that the agent cannot connect anything and must never ask a human to paste credentials.

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 purpose, then the search behavior, then the routing rules. It is long and dense but nearly every sentence carries distinct routing or safety value. Slightly heavy for a summary line, but no clearly wasted 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 no output schema, the description fills the gap by describing the return payload: lanes (oauth/key/provision/broker), connected flag, public page, connect_url, and copyable_from with copy_url. Combined with full parameter coverage and annotation safety hints, an agent has everything needed to call and act on results.

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 (limit, query, connected) are already documented in the schema. The description adds only marginal framing ('narrow by name or purpose', 'leave it blank to list everything'), which largely restates the query parameter's own schema text. 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 ('see what services Connections can connect - the whole connector registry') with concrete examples, and explicitly contrasts with the sibling connections_search_catalog by noting that only connected connectors' endpoints are searchable there. An agent can distinguish this registry-listing tool from the catalog search 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?

Explicit when-to-use routing: pass a query to narrow vs blank to list all, use connections_search_catalog for a connected connector's endpoints, hand over connect_url when a needed service is missing, copyable_from/copy_url for other workspaces, and connections_copy_connection when cross_workspace_access is ON. It even states the boundary condition 'both workspaces are solely the member's'.

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, openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the exact shape of the response (one tool, fields, example, confirmation flag), the capability-map fallback, and that unknown argument names are surfaced in `ignored_params` rather than dropped. It does not state rate limits or latency, but none are implied for a local help router.

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 triggering condition, then the primary output, then the disambiguation parameter, then the no-match fallback. Every clause carries information; nothing is padding or restated name/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?

No output schema exists, and the description compensates fully by enumerating what comes back (single tool, required fields, optional fields, runnable example, confirmation flag) and what happens when nothing matches. For a zero-required-param router, an agent has everything needed to invoke and interpret it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the alias set and the domain disambiguation rationale that the schema already documents ('add could be a todo or a contact'), and the intent examples are duplicated in the schema. It adds little semantic payload beyond structured fields, though it usefully frames intent as 'the member's own words'.

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 function: routing an intent to the single correct Connections tool and returning its required fields, optional fields, a runnable example, and confirmation requirement. It also defines the secondary behavior (full capability map when intent is absent or matches nothing). This is unmistakably distinct from every connections_* sibling, which each perform concrete actions.

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

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

Explicitly says to use it BEFORE guessing which Connections tool to call, or when unsure what Connections can do at all, and explains that `domain` should be added when intent alone is ambiguous. Implicitly defines when not to use it (when the target tool is already known), and the fallback condition is spelled out precisely.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered; the closing 'Read-only, no side effects' largely restates them. The genuine added value is behavioral: links land the member already signed-in and immediately trigger the action, which an agent could not infer from 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?

Two tight sentences, front-loaded with the core definition and enumeration before the usage instruction. The trailing 'Read-only, no side effects' is redundant given the annotations, a small waste in an otherwise efficient description.

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

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

For a zero-parameter, no-output-schema tool, the description covers what is returned (signed-in deep links per action) and how to use them. It stops short of describing the shape of the returned collection (e.g., keyed by action versus a list), which is the one gap an agent might care about in the absence of an 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric this is the baseline 4. No parameter names or formats are needed.

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 concretely defines the resource: deep-link URLs that land a member signed-in and open a specific action, enumerating those actions (import contacts, import file, post deal, browse deals, add connector). It also names connections_pulse as the carrier of these links, which separates it from sibling action tools like connections_deal_create. The verb is implicit ('the contract: URLs that...') rather than an explicit 'returns the deep-link URLs', which keeps it just short of a 5.

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

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

It gives explicit routing guidance: 'Hand one to the member in chat instead of describing the steps,' which states both the use case and the alternative it replaces. It further tells the agent where these links already surface (connections_pulse's next_actions on the relevant action), so the agent can decide whether to call this at all.

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 mark the tool as read-only (readOnlyHint: true). The description adds the behavioral context that the companies are those 'this signed-in account can bind a registration to' and explains the owner field for distinguishing duplicate names. No side effects are mentioned, but they are not needed given the read-only annotation and the tool's listing nature.

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

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

The description is a single, well-structured sentence. It front-loads the action and resource, then provides necessary details (output fields, duplicate handling) and a usage hint, with no redundant 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?

Even without an output schema, the description lists the returned fields (companyId, display name, owner) and explains their purpose. It also places the tool in a workflow with claim_company and whoami, making it clear when and why to use it. This provides complete context for an agent.

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 schema coverage is effectively 100%. Per the rubric, high schema coverage yields a baseline of 3; the description does not need to elaborate on inputs since there are none.

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 clearly states the action ('List'), the resource ('companies'), and the scope ('available to this account'). It also explains the output fields and references sibling tools (claim_company, whoami) for context, making its purpose unambiguous and distinct from other tools.

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

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

Explicitly provides a usage scenario: 'Use together with connections_claim_company when connections_whoami reports company:null.' This gives clear when-to-use guidance and indicates the expected workflow, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already mark it destructive and idempotent, but the description adds substantial context beyond them: retire disables the registration, nothing ever deletes, restore undoes retire, the 10-minute recent-use guard with force:true, and the bypass-permissions requirement producing a studio_only reply. These are non-obvious behaviors an agent needs.

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

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

Long, but front-loaded with the action framing and each clause carries distinct operational content (list semantics, assign criteria, retire criteria, guard rail, auth failure mode). Slightly dense to the point of being a wall of text, but no wasted 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?

No output schema, yet the description describes the reply shape ('leads with how many are unassigned') and the two error/refusal modes (force guard, studio_only), plus confirms listing always works. Complete for a 4-param stateful admin 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%, so baseline is 3, but the description adds meaning beyond the schema: `server` accepts an ARRAY for backlog operations, `workspace` takes a companyId or exact name, and force only applies to retire on recently-seen servers. Marginal but genuine added value.

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 ('every MCP server this account has registered... and which workspace it runs in') and enumerates the action surface (list/assign/retire/restore). Clearly distinguishable from sibling tools like connections_accounts or connections_list_companies.

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 triggers ('CALL IT WITH action:list whenever the member asks what is connected, why an assistant is in the wrong place, or why a server is not doing anything') and explicit selection rules between assign and retire, including the 'an unassigned server is not automatically one to assign' exclusion.

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

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

Annotations already declare non-readOnly, non-idempotent, destructive, closed-world, so the safety profile is largely covered. The description still adds real behavior: exactly ONE note is created, the destination is resolved to the bound workspace or personal space, and the reply names which (so the agent should echo it back). It does not explain why the call is flagged destructive or what happens to an existing note with a similar title, leaving a modest gap.

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

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

Front-loads the trigger condition, then the creation semantics, then destination resolution, then the sibling exclusion - a sensible ordering. Slightly dense but nearly every clause carries instruction value; the 'so say it back' aside is short and actionable.

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

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

For a 4-parameter mutation tool with no output schema, the description covers the trigger, the destination resolution, and the follow-up behavior (reply names the space), which is most of what an agent needs. The only unaddressed item is the destructiveHint=true flag, which the description neither explains nor contradicts.

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 already 100%, so the baseline is 3. The description adds styling guidance beyond the schema by telling the agent to keep the title to one line naming the thing and to put the remaining content in `body`, plus it restates the scope default resolution in prose.

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 ('Creates ONE new note on the member's Connections list') and immediately contrasts with the sibling it is not: connections_todo_add for tasks and reminders. An agent can distinguish it from connections_notes_search and connections_todo_add 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 trigger phrases the member might use ('save this', 'make a note of that', 'write this down') and an explicit exclusion with a named alternative ('Not for a task or reminder - use connections_todo_add'). This is about as unambiguous as routing guidance gets.

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, non-destructive, closed-world), yet the description adds real behavioral detail beyond them: what content is included/excluded, that each row carries a preview, labels and a link, and that matching runs over title, body and labels. It does not disclose ordering guarantees or rate limits, keeping it just short of a 5.

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

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

Front-loads the trigger, then routing, then return behavior in a tight sequence; every sentence (inclusion/exclusion, row shape, query semantics) earns its place 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 no output schema, the description compensates by describing the row contents and the no-query/query behavior difference, which is exactly what an agent needs to call and interpret results 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 the schema already documents all six parameters, which sets the baseline at 3. The description reinforces query semantics (recent vs. best-match) and return content but adds little syntax or constraint detail beyond what the schema provides.

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

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

States a specific verb and resource ('Search the member's notes') and scopes the content precisely ('plain notes, open questions and saved prompts'). It explicitly carves itself away from the todo sibling, so an agent can distinguish 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?

Opens with an explicit when-to-use trigger ('when the member asks what they wrote, saved or noted about something...'), and names the alternative plus the condition that selects it ('never the to-do list (use connections_todo_list...instead)'). Nothing 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=false, openWorldHint=false, idempotentHint=true, destructiveHint=false; the description adds the persistence constraint ('until they click OK') and the human-in-the-loop UX. It does not state whether the highlight blocks or errors if the owner is offline, but that gap is minor given annotation coverage.

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

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

Three tight sentences: what it does, when to use it, and the one optional input. No filler; the target URL grounds the action 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 one-parameter, human-triggered debug tool with annotations covering the safety profile and no output schema, the description tells the agent everything needed to call it correctly and to know what the human will see.

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 there is only one optional parameter; the description repeats that the note is shown with the highlight but adds no format or length constraints. Baseline 3 is appropriate because the schema already carries the semantics.

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

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

States a specific action (highlight this exact registration on the MCP Servers page), the target (owner's page at a concrete URL), and the trigger (human clicks OK). No sibling in the list does anything similar, and the debugging intent ('which registration am I actually riding?') makes the tool's distinct role unmistakable.

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

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

Gives clear context (debugging which registration is active, human-triggered, user sees a highlight) but does not state when NOT to use it or name an alternative. The 'human triggers it' framing is useful, but a caveat like 'for live demos, prefer connections_pulse' is absent.

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/no-destructive/no-openWorld, but the description adds real behavioral context beyond them: 'unmetered, no side effects,' and the failure contract that any unreadable section returns its own {error, detail} instead of silently vanishing. That error-shape disclosure is exactly the kind of detail 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?

Front-loaded with the tool's role, then a single dense sentence enumerating the return contents. The long parenthetical list is information-dense and each item is useful, though the enumeration is heavy enough to slightly dilute scannability.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly: identity, deal counts and newest-with-links, personal counts, ranked next_actions with their connections_execute calls, and the voice summary. An agent knows precisely what it will receive.

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 and the schema is empty, so there is nothing to disambiguate; baseline 4 applies. No param meaning is required or missing.

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 role ('the session opener') and enumerates exactly what one read returns: identity/company binding, live deals with counts, contact and event counts, ranked next_actions, and a voice summary. It also differentiates itself from connections_whoami by noting it carries that answer inside it.

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?

Calling it 'the session opener' plus the note that it subsumes connections_whoami gives clear implied usage at session start. It stops short of an explicit when-not-to-use rule or naming alternatives for specific sub-reads, so it isn't a full 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 declare destructiveHint=true and readOnlyHint=false; the description is consistent with these and adds genuinely useful context beyond them: the tool does not mutate state directly but creates a pending, visible request the owner can approve or dismiss. It also discloses a hard limitation (cannot change its own binding). This human-in-the-loop, async behavior is exactly the kind of trait an agent needs to know.

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 with no filler; the core instruction is front-loaded, and the middle sentence efficiently packs the constraint, trigger scenario, and workflow outcome. The embedded example ('Cloudflare isn't connected...') adds concrete meaning rather than bloat.

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 having no output schema, the description covers what an agent needs to call the tool correctly: what to pass, where to source it, and what will happen as a result. The gaps are minor — no statement of what the tool returns (confirmation vs. error on an invalid company) and no mention of whether multiple pending requests are possible.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value on top by telling the agent where valid values come from (connections_list_companies) and specifying value precedence (companyId/projectId preferred over exact name), which the schema descriptions do not convey.

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

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

States a specific action ('Ask the human to move THIS registration to a different company'), names the resource, and emphasizes that it is a request needing owner approval rather than a direct change. The title reinforces this approval-bound workflow, distinguishing it clearly from siblings like connections_claim_company or any direct-mutation 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?

Provides an explicit trigger condition ('when you suspect you're on the wrong company... request the right one') with a concrete example (missing connected service), and explains the downstream effect (highlight on MCP Servers page for approval/dismissal). It discloses that the binding cannot be changed directly (Studio-only), implying the manual alternative, but it never explicitly names an alternative tool to prefer or states when not to use it.

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

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

The description reinforces the destructive nature of the operation beyond the destructiveHint annotation by mentioning 'tier-locked' and 'Always allowed.' It does not mention irreversibility or side effects, but the word 'delete' and the annotation provide adequate transparency.

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

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

The description is a single, focused sentence with no redundant wording. It front-loads the action and target, and the additional permission context is compact and relevant.

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

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

For a simple delete operation with no output schema, the description provides necessary context about ownership and tier-locked restrictions. It does not specify return behavior or error cases, but those are commonly implicit for deletion tools.

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 only parameter, tool_name, is described as 'The script to delete,' which is accurate but minimal. Since the schema already fully covers this single parameter, the description adds limited extra semantic value.

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 clearly states the action ('Delete'), the target ('stored scripts'), and the selection mechanism ('by tool_name'). It also distinguishes this from sibling tools like script_get and script_save by focusing on deletion.

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 states when deletion is allowed ('Always allowed for your own company's rows') and includes a practical example ('deleting is how a downgraded account trims its vault'). It does not explicitly describe when to avoid using it, but the scope limitation is clear.

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

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

Annotations cover the read-only safety profile, and the description adds substantial context beyond them: tier-gated access, the script_locked_by_tier error and that the script is kept not deleted, and that list mode never returns code. That is exactly the behavioral detail annotations don't provide.

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

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

One dense paragraph, front-loaded with the two modes and the automatic-call caveat before paging and tier details. Efficient, though the pagination and error clauses push it toward the longer end for a three-parameter 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?

No output schema, yet the description discloses what each mode returns (code+metadata vs metadata+size+locked status, never code) and how paging works via total_count/next_offset. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents limit, offset/next_offset, and tool_name's omit-to-list semantics, so the description largely restates them. It adds a mode-level framing (tool_name as the mode switch) but 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 and resource and cleanly splits two modes: 'fetch ONE stored script's code + metadata' vs 'list this company's stored scripts'. An agent can distinguish this from siblings like connections_script_save/delete 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 when-to-use condition ('call it directly only to inspect or port code') plus context that script_run calls it automatically, and the mode switch (tool_name present/absent) is spelled out. Nothing 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely useful context beyond them: restoration is exact and identity-preserving, deletion is retained for a plan-specific Trash window, and specific error outcomes are enumerated. It does not describe permissions or the shape of the returned list, 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 sentences, densely packed with no filler, and the primary restore action is front-loaded before the listing mode and error conditions. The final sentence is somewhat compressed and run-on, which slightly hurts readability.

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

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

With no output schema, the description correctly compensates by explaining what the no-argument mode returns (the company's deleted scripts) and what error answers mean (already_exists, upgrade door). For a two-param, zero-required tool this is close to complete, though permissions and list output shape remain unspecified.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces the omit-tool_name listing behavior and adds the rationale that script_id disambiguates repeat deletions of the same name, but adds little syntax or format detail beyond structured data – 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?

Names a specific verb (restore) and resource (deleted Script Vault script), states exactly what is recovered (code, parameters, description, same tool_name), and adds a distinct second mode (list deleted scripts when tool_name is omitted). This clearly separates it from the sibling set (script_delete, script_save, script_get).

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 tells the agent when to omit tool_name (to list retained deleted scripts) versus supplying it to restore, and flags the two failure branches (already_exists, past the plan's Trash window). It stops short of naming sibling alternatives for those situations, which keeps it just under 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?

The description thoroughly discloses behavioral traits: it upserts per tool_name, never executes scripts on the server, enforces size tier limits (with rejection and locking behavior), and explains that the description is the search index. It complements the annotations (destructiveHint=true) by detailing the mutation semantics and constraints, adding significant value beyond what annotations alone 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 lengthy but each sentence carries functional information: purpose, upsert, language, execution model, size limits, and description guidance. It is front-loaded with the primary action and progressively adds operational details. No redundancy; the length is justified by the tool's complexity and the need to communicate multiple constraints.

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 tool with 8 parameters, nested objects, and no output schema, the description covers purpose, usage, behavioral quirks (size tiers, locking), parameter roles, and integration with sibling tools. It addresses everything an agent needs to correctly invoke and understand the save action, including edge cases like downgrades and over-limit saves.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that tool_name is a stable slug used for upsert, that description is the search index, that language defaults to javascript/node with bun as an option, and that destructive indicates whether the script mutates things. It also connects parameters to the execution environment (CONNECTIONS_SCRIPT_ARGS).

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 clearly states a specific verb (save/upsert) and resource (script instrument into Script Vault), and it distinguishes itself from siblings like connections_script_delete, connections_script_get, and connections_search_catalog by explaining the full lifecycle (save → discover via search → run via script_run). The purpose is unmistakable.

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

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

It explains when to use this tool (to persist a reusable script for future sessions) and provides context on how it integrates with search_catalog and script_run. It also gives guidance on writing descriptions for discoverability. It doesn't explicitly state when not to use it, but the naming and purpose clearly separate it from delete/get tools, and the upsert semantics are explained.

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

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

Annotations already establish it is a safe read-only, open-world search, so the bar is lower, and the description goes well beyond them: it discloses that results are runnable recipes, that exact tool_name matches rank first over fuzzy hits, that the catalog is tens of thousands of rows and cannot be listed wholesale, and that blank queries yield a browse view. This is unusually rich 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?

Usage guidance is front-loaded, but the body is two very long, em-dash-heavy sentences with a bloated domain enumeration ('contacts and people, notes and memories, events and guest lists...'). The information is relevant, but the wall-of-text structure hurts scanability and could be tightened considerably.

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

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

With no output schema, the description carries the return-format burden and does so: recipes, endpoint_id handoff to connections_execute, verbose-based shape control, and the browse-vs-list distinction. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and baseline is 3. The description adds genuinely new semantics beyond the schema: the blank-query browse behavior, the interaction of `service` with a blank query to list one service's rows, and the precedence rules for exact tool_name matches.

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

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

States a specific verb (search) and resource (the Connections operator catalog of API endpoints) and enumerates the covered domains: contacts, notes, events, deals, bookings, email, orders, payments, connected services. It also distinguishes itself from the dedicated siblings in the roster by scoping to 'anything Connections holds that has no dedicated tool in this roster.'

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

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

Gives clear when-to-use guidance: reach for it when no dedicated roster tool covers the request, or when you need an endpoint by name, and it routes forward to connections_execute via endpoint_id. It does not name specific alternative tools (e.g. connections_notes_search, connections_contacts_list) explicitly, only referring to the roster generically, so the exclusion is implied rather than enumerated.

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, but the description goes further and says exactly what is destroyed: the session ends for good, every tool stops working until reconnect, and reconnect is a few clicks in the assistant's own settings. It also discloses that the reply itself carries the reconnect steps, which must be read back verbatim.

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 usage condition is front-loaded in the first sentence and every subsequent sentence adds routing, irreversibility, or reply-handling information. Dense and slightly long for a one-parameter tool, but 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?

No output schema exists, yet the description compensates by explaining that the reply carries reconnect steps and must be relayed verbatim. For a destructive terminal operation, the agent has everything needed to call it correctly and handle the result.

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

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

Schema coverage is 100% and the single param already documents both 'must be true' and the confirmation precondition, so the description mostly restates it. It adds only mild reinforcement of the confirmation gate rather than new syntax or semantics; 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 (sign this connection out of Connections) and immediately distinguishes it from the nearest sibling by naming connections_switch_workspace as the wrong tool for a mere workspace change. An agent can pick between the two 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?

Explicit trigger (member is signed in as the WRONG account and wants to sign out/switch), explicit exclusion (if they only want a different WORKSPACE, use connections_switch_workspace instead), and an explicit precondition on confirm. When/when-not/alternative 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 cover safety (readOnly=false, idempotent=true, destructive=false), and the description goes well beyond them: it discloses that only THIS connection moves, that the change is effective on the next call, that nothing is copied or deleted, and that remember:true affects future assistant connections. These are real behavioral traits an agent must know.

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 trigger condition and stays on task, but the dense run-on sentences and shouted emphasis ('STRAIGHT AWAY', 'do NOT') make it longer than necessary. Every clause is informative, but it could be tightened without losing meaning.

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

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

No output schema exists, so the description carries the return-value burden, and it does: it explains that a single alternative resolves silently and reports where it landed, while multiple alternatives return choices. Combined with trigger and remember semantics, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning the schema lacks: OMIT `workspace` when unnamed, with single vs. multiple alternatives producing different returns. It also reinforces the opt-in nature of `remember`. Slight overlap with the schema keeps it from a 5.

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

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

States a specific verb (switch) and resource (which workspace this connection uses), and explicitly differentiates from the sibling connections_list_companies by telling the agent NOT to call it first. An agent can identify the tool's job and its boundaries 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 trigger phrases ('wrong workspace', 'switch me to <name>', confirmed switch after missing data), states when to call with no argument versus with `workspace`, and names the alternative it is not (connections_list_companies). The single-vs-multiple workspace decision tree 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?

Discloses non-obvious behavior beyond annotations: creates one open to-do, selects workspace vs personal based on connection binding, requires the reply to name which space, and specifies title/body formatting. This substantially supplements annotations that only carry generic false hints.

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, front-loaded sentences: trigger conditions first, then behavior, then the exclusion. Every sentence carries operational value, and the examples are illustrative rather than redundant.

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

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

For a 5-parameter, no-output-schema tool, the description covers when to use it, what it creates, where it places the to-do, how to format the title/body, and which alternative to use instead. The instruction to say the placement back to the member covers the key response detail.

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 input schema already describes all 5 parameters, so the baseline is 3. The description reinforces the title/body split and the scope default but does not add new parameter-level details beyond what the schema already provides.

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

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

States a specific action ('add/save/note or remember a to-do') against a specific resource (the member's Connections list), with trigger-phrase examples. It clearly distinguishes itself from post_agent_todos_add and is unambiguous against siblings like connections_todo_done and connections_todo_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?

Opens by telling the agent exactly when to use it: when the member asks to add, save, note, or remember a to-do/reminder/follow-up, including concrete phrases. It explicitly says not to use it for the assistant's own intended work and names post_agent_todos_add as the alternative.

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 meaningful behavioral detail beyond the annotations: it explicitly says the item is 'marked, never deleted' and that the operation is reversible via `done: false`. This complements idempotentHint and destructiveHint without contradicting them.

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 compact and well-structured: trigger conditions first, then parameter mechanics, then reversibility. Every sentence earns its place and there is no redundant or vague wording.

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

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

For a simple two-parameter toggle tool, the description covers the trigger, the id source, the `done` flag behavior, and the safety guarantee. No output schema is present, but the outcome is sufficiently implied by 'the item is marked'.

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 description essentially restates the schema's parameter info: `id` comes from connections_todo_list and `done: false` reopens. It adds no deeper semantics beyond what the input schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's action: checking a to-do off or reopening it based on the member's report. It names the resource (a to-do identified by `id`) and distinguishes itself from sibling tools like connections_todo_add and connections_todo_list by focusing on the completion/reopen 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?

It gives explicit positive usage triggers ('done, finished, completed, handled - or should be reopened') and specifies that the correct `id` comes from connections_todo_list. However, it does not explicitly state when NOT to use this tool, such as for adding new to-dos, so it stops short of full when/when-not coverage.

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

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

Annotations already establish readOnly/non-destructive/closed-world, so the bar is lower, and the description still adds real behavioral context: results span personal space plus every workspace, the connection's workspace is ordered first, and open items are the default. It does not mention truncation behavior when limit is hit, which is the only notable gap.

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

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

Front-loaded with the trigger phrasings, then the return shape, then the exclusion. The enumeration of query phrasings is long but each maps to a distinct user utterance, so it earns most of its space; a slightly tighter list would still read well.

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

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

With no output schema, the description carries the return-value burden and does so: it says what items come back by default, what fields accompany each, and which scope wins for ordering. Combined with full schema coverage and annotations, 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% so the baseline is 3, but the description adds semantics the schema lacks, notably the result ordering ('the workspace this connection is in first') and the default result shape (open items with due date, labels, workspace). It reinforces rather than repeats the scope/default meanings.

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 (member's Connections to-do list) and enumerates the surface forms of the question it answers. It also names the sibling lane it is not (post_agent_todos_list), so an agent can separate it from the other to-do-adjacent tools 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?

Explicit trigger conditions ('when the member asks what is on their to-do list... due or overdue... whether anything is waiting on them') plus an explicit instruction to answer only from this list, never chat history, and an explicit exclusion for the agent's own work log. Both when and when-not 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 readOnlyHint=true and destructiveHint=false; the description adds 'Read-only, cheap, no side effects' and explains nuanced behavioral output such as 'explicit company:null when unassigned' and the assignment-source enum. It does not contradict the annotations and provides context beyond the 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?

The description is long but information-dense, with the core answer front-loaded and each subsequent sentence adding distinct value: usage triggers, return fields, alternatives, and safety profile. It earns its length, though it is slightly verbose with the repeated emphasis on account/workspace.

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

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

With no output schema, the description fully covers what the agent will receive: the human-readable account name/email, registration, machine label, bound company or null, assignment source, and active status. It also addresses common follow-up actions and relationship to connections_pulse, making the tool self-contained 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?

The tool has zero parameters, so the baseline is 4; there is no parameter schema for the description to compensate for. The description instead clarifies how to interpret the response's `say` line, which is the relevant semantic information for an agent calling this tool.

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

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

The description opens with 'WHICH ACCOUNT AND WHICH WORKSPACE THIS CONNECTION IS ON', a specific identity/inspection purpose that is instantly clear. It also names the returned binding details ('registration', 'company', 'assignment source') and explicitly distinguishes this tool from connections_pulse, making the scope unmistakable.

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

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

It gives explicit when-to-use guidance: 'Call it the moment the member wonders about either' with quoted user questions. It also names the exact corrective tools for wrong workspace (connections_switch_workspace) and wrong account (connections_signout), and tells the agent to prefer this tool over connections_pulse when only the binding is needed.

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=false, so safety is covered. The description adds real behavioral value beyond that: the exact error contract ({ error: 'unknown_id' }) for unrecognized ids and for note ids on unbound connections, which an agent cannot infer from 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?

Three sentences, each carrying distinct information (what it resolves, error behavior, intended client), with the core purpose front-loaded. Dense but nothing is wasted.

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

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

There is no output schema, yet the description fully specifies the returned record shape ({ id, title, text, url, metadata }) and the failure shape. Combined with annotations covering the safety profile, 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?

Schema coverage is 100% and the sole param is documented, so the baseline is 3. The description goes further by revealing the id's expected format ('deal:<id>' or 'note:<id>'), which the schema does not state, materially improving correct invocation.

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 (resolve) and resource (one id returned by search, a deal or note) and distinguishes it from the sibling `search` by making clear this is the reverse lookup that returns full records rather than ids. An agent can tell exactly what this 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?

Clearly frames the tool as the fetch half of a search/fetch pair and names the client mode that needs it (ChatGPT chat connector), and the id is stated to come from `search`. It stops short of an explicit 'do not use this to search' exclusion, but the routing context is strong.

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, non-destructive, closed-world), and the description adds real context beyond them: a per-surface cap of 10 results, the exact return shape { results: [{id, title, url}] }, and the round-trip contract that each id feeds into `fetch`. It stops short of error or empty-result behavior, but for a read-only search 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 dense sentences, front-loaded with what is searched and the return shape. The final client-compatibility sentence earns its place by routing between this and the native roster, though it is the most compressible part.

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

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

With no output schema, the description correctly supplies the return format and result cap, and it flags the conditional availability of notes. An agent has enough to call it correctly; only edge-case behavior is unspecified.

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, whose schema already documents it fully at 100% coverage. The phrase 'filtered by this query' confirms the query narrows the public feed, which is marginal added meaning. Baseline 3 is correct 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?

Specific verb plus two clearly-named resources: the public marketplace deals feed filtered by query, and the member's own notes. It distinguishes itself from siblings notes_search and deals_list by covering both surfaces in one call, so an agent can tell immediately what this tool does that the others don't.

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 scopes use to clients that only speak search/fetch (naming ChatGPT's chat connector mode) and routes the agent to connections_pulse and connections_execute for the full native roster. It also states the precondition that notes only appear 'once this connection is bound to a company'.

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