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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral content by disclosing that install_url is null for coming_soon add-ons and explicitly warns never to invent a store link, plus it explains the `say` field for member-facing output.

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

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

The description is front-loaded with the core purpose, followed by return fields and a critical edge-case instruction. Every sentence adds distinct value, and there is no redundant 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 parameters, no output schema, and annotations already covering the safety profile, the description provides everything an agent needs: what the tool returns, how to interpret the `say` field, and how to handle the null install_url case.

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

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

The tool has zero parameters, which sets the baseline at 4. There is no parameter surface for the description to clarify further.

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

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

The description states a specific verb-resource pair: it returns available Chrome add-ons for Connections Email, Calendar, and Notes. It clearly distinguishes itself from sibling connectors by scoping to external browser add-ons and listing the exact fields returned.

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

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

The description implies use when explaining what Connections offers outside the chat, and it gives a clear conditional instruction for the coming_soon/null install_url case. It does not explicitly name when not to use the tool versus alternatives, but no direct sibling competes for the same resource.

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 are minimal (all false hints), so the description carries the burden. It discloses that the tool creates (not just modifies) and that the event is on the member's own calendar, visible only to them, which is significant behavioral context. It also states defaults for ends_at and all_day, and explains the reply behavior ('The reply names what was added and when, so say it back'). It doesn't cover failure modes or idempotency, but given the annotations are sparse, this is a strong effort.

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 dense paragraph but each sentence earns its place: trigger phrases, scope, parameter details, reply expectation, and alternatives. It front-loads the 'use this when' instruction and structures the rest logically. No filler or 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?

Given no output schema, the description hints at the reply ('names what was added and when'), which is enough for a simple creation tool. It covers all parameters, defaults, and alternative routing. It doesn't address potential errors or validation limits, but for this scale of tool, that's a minor omission. Overall it gives an agent everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes far beyond the schema. It explains the ISO format with an example including UTC offset, clarifies how all_day interacts with starts_at, states the ends_at default, and clarifies that title should be 'in the member's words'. This adds critical semantic detail that the agent needs to invoke correctly, especially the offset requirement.

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 'Use this when the member asks to add, put or schedule something on their calendar' and lists concrete example phrasings, then specifies it creates ONE event on the member's own Connections calendar visible only to them. It clearly differentiates from public events and todos, so an agent can distinguish it from siblings without ambiguity.

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

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

It gives explicit trigger conditions ('add it to my calendar', 'block out 2-4pm') and names alternatives with the condition that selects them: 'For a public event with its own page, tickets or RSVPs use connections_event_create; for a to-do with no time slot use connections_todo_add.' This is textbook guidance on when and when not to use the 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 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?

Annotations declare destructiveHint=true and openWorldHint=true, but the description adds substantial behavior beyond them: SSRF guarding on both lanes, rows stamped source='agent-added', host allowlist enforcement for non-AWS services, auth-scheme inheritance rules, and the fact that the response reports auth_scheme_source plus a warning on scheme mismatch. This is rich, non-redundant disclosure.

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 is front-loaded and every clause carries information (lane rules, constraints, alternatives). It is unusually dense for a single paragraph with nested parentheticals, which hurts scannability slightly, but there is essentially no wasted 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 23-parameter, nested-object, no-output-schema tool this is complete: both lanes, auth inheritance, SSRF constraints, upsert/repair semantics, and even the response fields are covered. Nothing an agent needs to call it safely appears to be 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 schema already documents each field thoroughly, so the baseline is 3. The description goes further by encoding cross-field dependencies that the flat schema cannot express — protocol + action+version OR target+jsonVersion, apikey/header requiring header/headerPrefix, and query requiring `param` — which materially changes how an agent fills the parameters.

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?

Starts with a specific verb+resource+outcome: adds an operation to the LIVE catalog so it becomes reusable via connections_execute. It also names the sibling alternatives (aws_call, connections_catalog_remove) and its role as the 'self-improvement path', so an agent can distinguish it from neighbors without opening a schema.

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

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

Gives explicit when-to-use ('when an op is missing'), explicit alternatives and exclusions ('for a one-off AWS call prefer aws_call'; 'to remove/repair a row, connections_catalog_remove'), and clear branch conditions for the AWS vs non-AWS lanes.

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 indicate destructiveHint=true, but the description elaborates: it upserts changed operations and prunes dropped ones, and clarifies it only restores discoverability, not forwarding of unknown params. This goes beyond annotations to explain side effects and limitations.

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 every sentence adds value: purpose, use case, constraints, and behavior. It's front-loaded with the core action and then elaborates. 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?

Covers purpose, when to use, constraints, and effects. It lacks an explicit success/failure return description, but given no output schema and the focus on mutation, it's sufficient. The unknown-value return behavior is noted. Could mention confirmation of refresh, but not essential.

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 already fully documents the single parameter `service` with examples and unknown-value behavior, so description adds little new about the parameter itself. It does add context about server-side allowlist, but that's more tool behavior than parameter 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 're-ingest', a resource 'first-party plane's LIVE /openapi.json', and an outcome 'into the operator catalog'. It explicitly contrasts with scheduled sync and search_catalog showing old schema, so it's clear what problem it solves.

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 it's the fix for when search_catalog shows old schema, and that it makes new endpoints discoverable immediately vs scheduled sync. Also states constraints: must be allowlisted plane, OpenAPI URL is server-side, unknown value returns full list. This clearly tells an agent when 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?

Annotations carry the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=true) and the description adds substantial non-obvious behavior: agent-added rows are removed on request while other rows require the server's credential-free probe to return a vendor no-such-route answer; unreachable vendors leave rows in place with an explanation; bulk calls judge each row independently and report the justifying probe. 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?

All six sentences carry distinct functional content and the highest-stakes information (what gets removed and under what conditions) is front-loaded. The middle clause ('the server's own credential-free probe of the vendor gets the vendor's published no-such-route answer') is dense and slightly convoluted, but the length is justified by the tool's conditional 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?

For a destructive, open-world tool with no output schema, the description is remarkably complete: it covers both use cases, all three targeting modes, the conditional removal policy for agent-added vs. all other row origins, failure behavior for unreachable vendors, per-row probe reporting, and the preferred alternative for fixing rows. An agent has everything it needs to decide whether, how, and with what expectation to invoke 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 parameter meanings are already documented. The description adds genuine value by explaining how to choose among the targeting lanes (endpoint_id/tool_name for single, endpoint_ids for bulk), the 'aws' service default, the max-200 cap, and the independent per-row judging semantics — going beyond the baseline 3 without fully compensating for the absence of output-schema detail.

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 ('Remove catalog rows') and immediately distinguishes the two intended use cases: repair of a bad/duplicate agent-added row and cleanup of rows whose vendor deleted the route. The final sentence explicitly contrasts with connections_catalog_add, so an agent can tell these siblings apart without opening either schema.

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

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

Gives explicit when-to-use guidance for both lanes (repair vs. cleanup), explicit targeting guidance (ONE by endpoint_id/tool_name vs MANY by endpoint_ids), and explicitly names the alternative: 'To FIX a row in place instead of deleting it, just re-run connections_catalog_add.' 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?

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?

Annotations already indicate mutation and destructiveness, and the description adds meaningful behavioral detail: the copy shares the source's credential without duplicating, reading, or returning secrets; overwrite lands the copy first, disconnects the old row, and takes its name; the response shape is listed. There is 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 long but information-dense, and every clause earns its place. It front-loads the core purpose and credential-sharing behavior before covering error conditions, parameter alternatives, overwrite semantics, and return values. Nothing is redundant for a six-parameter tool with these edge cases.

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 covers permission prerequisites, error responses, parameter relationships, fallback actions, overwrite behavior, and return fields. There is no output schema, but the description states the returned object. An agent has enough context to call this tool correctly without guessing.

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?

Although the schema already documents all six parameters, the description adds substantial cross-parameter semantics: exactly one of connectionId or service+instance must be provided, with error names for both-or-neither; fromProject has a default and a disambiguation purpose; overwrite is tied to the target workspace. This goes far beyond the schema's individual field 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 and resource: copy one connected service from one of the member's workspaces into another. It also distinguishes itself from related tools by naming connections_explore_connectors as the fallback for cross-workspace-refused cases and by focusing narrowly on copying, not listing, creating, or managing connections.

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 the tool is allowed (cross-workspace access ON, both workspaces solely the member's) and when it is not, including the exact instruction not to retry and to hand over the copy_url from connections_explore_connectors instead. It also gives precise guidance on choosing connectionId vs service+instance and when to pass fromProject.

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 indicate mutating/non-destructive behavior, but the description adds significant behavioral detail: publish timing rules, paid-plan live listing limits, the specific free-plan error behavior, and dry_run's no-side-effect guarantee. This goes well beyond the structured annotations 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 front-loaded with the usage trigger and uses four dense, purposeful sentences. Each sentence adds distinct information: when to use, creation/publishing behavior, plan limitations, and dry_run. There is no filler or redundancy.

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

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

For a 13-parameter creation tool with no output schema, the description covers the critical runtime behaviors an agent needs: success criteria, draft vs. live, plan gating, error behavior, and a safe preview mode. The remaining optional parameters are fully documented in the input schema, so nothing essential to invoking the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the publish/draft distinction, the exact title + full_description requirement for going live, and the plan-dependent outcome when publish is true. This is valuable parameter-level context not present in the schema alone.

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: 'post a deal' on Deal Flow, and enumerates exact member intents (list a raise, sell a business or asset, look for a partner/buyer/investment). It also states 'Creates one deal,' which clearly separates it from sibling list/read tools like 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?

It explicitly says 'Use this when the member asks to post a deal...' and adds conditional guidance for publishing vs. saving a draft, including the free-plan limitation. It does not explicitly name when not to use it or point to an alternative tool, but the context is clear enough for an agent to select 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds non-obvious behavior: the public feed is always active and only ever holds active listings, while drafts/closed deals surface only under scope 'mine', and the feed relevance-ranks a query. It does not cover pagination behavior or result caps, but that is minor against the annotation coverage.

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

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

Front-loaded with the trigger, then scope semantics, then filtering, then the return-row composition, then the sibling hand-off. Each sentence carries information, though the scope explanation is repeated between the description and the schema's 'scope'/'status' fields.

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 enumerating what each returned row carries (title, summary, category, region, capital sought, status, link), and it explains defaults and scope-dependent visibility. Only pagination/limit behavior and the 'fields'/'detail' projection interaction are left to the schema.

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

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

Schema description coverage is 100% and every parameter (scope, detail, fields, status, limit, offset, region, category, query) is already documented inline, including the status/scope interaction. The description largely restates those semantics, adding only the relevance-ranking note and the scope default. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource (browse deals / the member's own listings) and names the distinct retrieval modes ('feed' vs 'mine'). It also names the sibling it is not ('To post a new deal, use connections_deal_create'), so an agent can separate it from connections_deal_create 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?

Opens with an explicit trigger list ('when the member asks about Deal Flow, deals, listings, what is for sale, raises, or their own postings') and hand-offs to the sibling that handles the excluded case (creating a deal). Both the when-to-use and the when-not-to-use condition are stated.

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

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

Annotations already declare readOnlyHint=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?

Beyond the annotations, the description discloses key behavioral traits: the message is irreversible ('cannot be recalled'), dry_run:true prevents sending, the sender must be on a verified connected domain, and failure returns named error reasons (suppressed recipient, unverified domain, daily ceiling, credits). This is rich behavioral context that the sparse annotations do not 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?

The description is compact but information-dense: trigger, core behavior, irreversibility, dry-run, domain prerequisite, error behavior, and sibling routing are all present in five sentences. It is front-loaded with the use case and contains no redundant 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 complex 13-parameter send tool with no output schema, the description covers purpose, usage, prerequites, failure behavior, and sibling tools. The only notable gap is that it does not describe the success response shape (e.g., message ID), which would be useful since there is no output schema to rely on.

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 13 parameters. The description adds no parameter-specific meaning beyond the schema, only general send behavior. This matches the baseline 3 for full schema coverage.

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

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

The description opens with a specific use case ('when the member asks to send or email someone from their own business domain') and names the tool's action as sending ONE real message. It also differentiates from siblings by pointing to connections_email_get and connections_emails_list for follow-up tasks.

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 says when to use the tool ('Use this when the member asks to send...') and provides sibling alternatives for related tasks ('To check on a sent message use connections_email_get; to see what went out use connections_emails_list'). This gives the agent clear routing guidance.

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

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

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?

The description adds substantial behavioral context beyond the annotations: the event is created as a draft, a draft is private until published, it does not add anything to the member's calendar, and dry_run:true creates nothing while returning what would be created. These details materially shape how an agent should invoke the tool and 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?

Every sentence earns its place: the trigger phrases, the public-event scoping, the draft behavior, the calendar exclusion, and the dry-run guidance. The description is front-loaded with the core when-to-use condition and contains no filler or redundant restatements of the tool name.

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 create tool with weak annotations and no output schema, the description is largely complete: it covers scope, draft visibility, the no-calendar caveat, and a safe dry-run path. It does not explicitly describe what the real (non-dry-run) response contains, but the dry-run behavior implies the returned event shape, leaving only a minor gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the input schema. The description adds workflow guidance around dry_run, but does not explain the semantic meaning of parameters like starts_at, ends_at, or location beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'create, host, plan or set up a PUBLIC event' and 'Creates ONE hosted event on Connections - its own public page with RSVPs and tickets'. It clearly distinguishes this public-event creation tool from related concepts like calendar events, making its purpose 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?

The description explicitly tells when to use the tool ('when the member asks to create, host, plan or set up a PUBLIC event') and when not to: for 'add it to my calendar', a meeting, appointment, or blocked-out time, use connections_calendar_add instead. It also provides a concrete pre-write workflow with dry_run, leaving no ambiguity about 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 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 declare destructiveHint:true and readOnlyHint:false, and the description adds substantial behavioral context: money-moving ops are blocked and redirected to the dashboard; third-party services use stored credentials; workflow has a ~24s time budget with partial-success responses; outputFilter reports outputFilterMatched:false with a raw snippet. No contradiction with annotations, and it discloses exactly what happens in edge cases like time budget and non-idempotent steps.

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 well-structured: it opens with the core purpose, then covers payment exclusions, workflow, credentials, FAST PATH, and response shaping in a logical order. Each section is dense with necessary detail; no filler. While it's not terse, the complexity of the tool justifies the length, and the front-loaded main purpose makes it navigable.

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's complexity (multiple modes, nested params, workflow, FAST PATH) and no output schema, the description covers what's needed to call it correctly: it explains how to select endpoints, run workflows, handle partial success, and use response shaping. It doesn't describe a generic response format, but since responses depend on the endpoint, that's acceptable. It fully covers the workflow edge cases and credentials, making it complete 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 coverage is 100%, so baseline is 3, but the description adds significant meaning: it explains the semantics of top-level params like project (which company/workspace), tool_name fallback for out-of-date tools, and instance targeting. It also details workflow inputs, time budget, and resume behavior, and clarifies FAST PATH params (e.g., rds_query uses plane names not ARNs, probe refuses private hosts). This goes well beyond the schema's 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 clearly states the tool executes a catalog endpoint or a multi-step workflow, with explicit selection via endpoint_id or service+tool_name. It distinguishes from search_catalog by focusing on execution, and details the FAST PATH for AWS ops, making the purpose unambiguous and differentiating it from siblings.

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

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

The description explains when to use it: for executing a known endpoint or workflow, and when not to for money-moving operations on payment providers (which return an error linking to the dashboard). It implies using connections_search_catalog to find endpoint_id, but doesn't explicitly say 'use this instead of search_catalog'—still, the context is clear enough for correct 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 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 the tool read-only and non-destructive; the description adds return-behavior context beyond annotations—returning a single recommended tool with fields/example/confirmation, or the full capability map with no intent. It is transparent about the no-intent fallback, though it does not detail response structure or edge cases beyond that.

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

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

Four dense sentences front-load the primary usage directive and keep every clause informative. Examples are compact, and the description does not restate schema fields 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 routing/help tool with no output schema, the description covers all call modes—intent, domain, and omitted intent—plus the shape of both possible outputs. An agent has enough information to invoke it correctly without needing additional documentation.

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 descriptions cover all five parameters, and the description builds on them by explaining intent semantics ('in the member's own words'), the disambiguation role of `domain`, and the alias/ignored_params behavior. This adds value beyond the schema, so it earns above the baseline 3.

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

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

The description opens with an explicit directive—'Use this BEFORE guessing which Connections tool to call'—and clearly identifies the resource (the Connections toolset) and the concrete output (the ONE tool to call, its fields, example, and confirmation requirement). This distinguishes the meta-routing helper from operation siblings like connections_todo_add or connections_event_create.

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 conditions ('BEFORE guessing', 'when unsure what Connections can do at all') and describes the fallback: no intent or unmatched intent returns the full capability map. It also instructs when to add `domain` to disambiguate, making the selection rule actionable.

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 indicate readOnlyHint=false and destructiveHint=true, but the description adds valuable behavioral detail: only local Connections MCP sessions, Studio console sessions, or cnx_live_ keys receive `values`, while assistant sessions only get `valuesWithheld`. It also explains the `describeOnly` mode's effect on the response. It does not elaborate on why the operation is marked destructive, but the added context still exceeds what structured annotations alone 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?

The description is dense and front-loaded with the core purpose, then provides necessary security and response-shape context. It is a long single block of text, which hurts skimmability, but nearly every clause adds useful information and none is redundant with the schema.

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

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

With no output schema, the description compensates by specifying the reply shape: `{service, instance, accountId, fields[], hints{}, primary}` plus `values` conditionally. It also covers the most important contextual constraints, such as which client types receive values. Minor gaps remain around lease lifecycle or destructive side effects, but the essential decision-making information is present.

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

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

Schema coverage is 100%, so the core parameter definitions exist. The description enhances them by explaining that `service` is a connected-service slug valid across all supported services, that `instance` supports AWS account IDs, and that `describeOnly: true` changes the response to field names and masked hints rather than values.

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: 'Return THIS company's stored credential for a connected service so a LOCAL script or vendor CLI can act with it.' It also differentiates itself from bespoke per-service tools and details the universal scope ('aws, stripe, cloudflare, github, twilio, openai').

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 clearly explains when to use the tool: for local scripts or CLIs that need a stored credential, and for describe-only mode when planning env vars. It names the usual integration path (local MCP's shell/script_run via their secrets parameter) but does not explicitly contrast it with specific sibling tools or give negative usage criteria.

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 explicitly states 'Read-only, no side effects,' which aligns perfectly with the annotations (readOnlyHint: true, destructiveHint: false). It also explains that the tool returns URLs that land the member signed-in and open actions, making the behavior transparent. There is no contradiction or hidden side effect.

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 concise, consisting of only two sentences. It front-loads the main purpose ('deep-link contract') and immediately provides examples and usage. There is no redundancy or unnecessary detail.

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's simplicity (no parameters, no output schema), the description is complete. It covers what the tool does, when to use it (in chat), and its relationship to connections_pulse. It also explicitly states its read-only nature, which addresses safety context. No gaps are apparent.

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 and an empty schema, so there is nothing to explain. According to the rubric, 0 params yields a baseline of 4. The description does not need to add parameter semantics, and it doesn't, which 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 clearly states the tool provides deep links for specific actions like importing contacts, posting deals, and browsing deals. It identifies the resource ('URLs') and the intended use case in chat. However, the term 'deep-link contract' is somewhat abstract and does not explicitly specify the output format (e.g., a list of links), which slightly reduces clarity.

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 a concrete usage guideline: 'Hand one to the member in chat instead of describing the steps.' It also notes that connections_pulse's next_actions already carry these links, suggesting a possible alternative source. However, it does not explicitly contrast this tool with sibling tools like connections_accounts or connections_execute, nor does it state when not to use it. The guidance is present but not fully explicit.

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

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

Annotations already 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?

Far beyond what the annotations convey: retire disables the registration exactly as Studio does and drops it out of the unassigned count, restore reverses it, 'nothing here ever deletes', retiring a recently-seen server errors unless force:true because an agent may be running on it, and every write requires the member's bypass-permissions setting or returns studio_only. That is rich operational context the annotations (readOnlyHint=false, idempotentHint=true) cannot express.

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

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

Dense but front-loaded: the list trigger comes first, then the assign/retire decision rule, then edge-case behavior and the permissions gate. Nearly every sentence carries a distinct operational fact, though the assign/retire guidance is stated twice in slightly different words.

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 still explains what the reply contains ('leads with how many are unassigned'), covers every failure mode the caller will hit (10-minute force guard, studio_only permission reply), and states that listing always works. 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 description coverage is 100%, so the schema already documents all four parameters, including the array-of-ids form and the workspace companyId/name choice. The description adds workflow meaning ('an id from the list') and the rationale for array batching, but largely restates what the schema provides, so baseline applies.

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

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

The description names the resource precisely ('Every MCP server this account has registered - each assistant, machine or connector - and which workspace it runs in') and enumerates the four lifecycle actions, so an agent knows this is the registration-management tool rather than a connector discovery tool like connections_explore_connectors. It is distinguishable from siblings without opening any schema.

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

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

It gives explicit activation triggers ('whenever the member asks what is connected, why an assistant is in the wrong place, or why a server is not doing anything'), names the default action, and routes to the specific alternative action for each condition. It also warns when NOT to act ('An unassigned server is not automatically one to assign - read the name first'), which is unusually strong 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?

Beyond the annotations' destructive/write hints, it discloses that execution happens in-lambda, uses the currently vaulted root key server-side, creates a standing role trusted by the new IAM user, keeps the new key in the vault, and returns {connection, userArn, roleArn}. It also explains the underlying AWS root-IAM limitation, giving the agent a clear model of 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?

Both sentences are dense and purposeful: the first front-loads the action and policy, the second explains the limitation being fixed and the resulting execution paths. There is no filler, redundancy, or repeated schema content.

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

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

For a complex mutation with no output schema, the description supplies the important context: prerequisite (already-connected ROOT-tagged instance), the narrower-than-AdministratorAccess policy, vault persistence, response payload, and how the new credential can be used via connections_execute and shell/script_run. Nothing essential for invocation is missing.

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

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

The input schema already has 100% parameter coverage, so the baseline is 3. The description reinforces the meaning of fromRootInstance (ROOT-tagged, source of authority, same account) and mentions storing the key on an instance, but it does not add significant new semantics beyond the schema.

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

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

States a very specific operation: mint an IAM user plus vault-operator role, apply an org+iam+sts:AssumeRole policy, and store the credential on an existing ROOT-tagged instance. This clearly differentiates it from generic credential tools and the sibling mint_plane_operator by tying it to root credential scoping and the exact reply payload.

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 a clear context: use this when a root AWS credential can reach Organizations/STS but IAM calls fail, and after the call the credential works through connections_execute and shell/script_run. It does not explicitly name an alternative or state when not to use it, 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?

It adds significant behavioral detail beyond the destructiveHint annotation: there is no dry-run, confirm must be true, the stored credential is overwritten in place, the org-enumerability check happens before any IAM write, and invalid accounts return an error with nothing changed. It also discloses that the minted key is written to the vault server-side and describes the reply shape.

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

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

The description is dense but every sentence earns its place: operation, diagnostic guidance, preconditions, and return contract are all included without filler. The core destructive behavior is front-loaded in the first sentence and the alert-level confirm requirement appears early.

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

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

For a destructive, cross-account minting tool with no output schema, the description covers prerequisites, the cross-account path, validation-before-write behavior, the no-dry-run requirement, and the exact response contract. Nothing an agent needs to safely invoke it is missing.

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

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

Although the input schema already covers 100% of parameters, the description enriches them materially: instanceName must be an EXACT existing dead instance and never invents a new one, targetAccountId must be enumerable by fromRootInstance via Organizations ListAccounts, and confirm acts as the sole safety gate with no dry-run. These meanings go beyond the schema's individual field 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 names a specific action and resource: 'mints a fresh scoped IAM operator credential THERE and overwrites the stored credential for that EXACT instance' in a MEMBER (plane) account. It clearly carves out this tool from the sibling connections_mint_org_operator by targeting member accounts rather than org accounts.

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 to diagnose first with aws_sweep across instances or the vault_operator_role_census instrument, and it specifies two preconditions (confirm must be true and targetAccountId must be org-enumerable) before any IAM write. It does not spell out the exact alternative-selection rule versus connections_mint_org_operator beyond 'MEMBER (plane) account' and 'Same contract', but the context 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?

The description discloses that the tool creates exactly one note, where it is stored (bound workspace or personal space), and instructs the agent to verbally confirm the location ('say it back'). These details go beyond the annotations, though non-idempotency is only weakly implied; the idempotentHint=false annotation covers that 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?

Four concise sentences, each carrying information: trigger phrases, creation/location behavior, title/body split, and the alternative tool. No filler or redundancy.

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

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

For a simple create tool with four documented parameters and no output schema, the description covers trigger, location, parameter intent, and alternative routing. Nothing critical 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; the description adds a useful division of labor between title and body ('Keep the title to one line... put the rest of the content in body') and reinforces the workspace/personal default from the scope enum. Labels are not expanded, but the schema already documents them.

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 concrete trigger phrases ('save, write down, jot or note something') and names the exact resource: a new note on the member's Connections list. It explicitly contrasts with connections_todo_add, so an agent can distinguish it from siblings without ambiguity.

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

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

It gives explicit when-to-use cue phrases and an explicit exclusion: 'Not for a task or reminder - use connections_todo_add for those.' It also clarifies the workspace-vs-personal placement rule, which is not obvious from the schema alone and prevents incorrect invocation.

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 indicate readOnlyHint=false and destructiveHint=true, so the description correctly implies a mutating action. It adds transparency by clarifying that the secret value is not exposed in replies, logs, or errors, which is a security-critical behavior not evident from annotations. It also discloses the default expiry of 6 months and the rationale (standing secret = standing capability), and mentions the returned keyId for revocation. The description slightly exceeds what annotations provide, though it doesn't detail the exact lease shape or all error conditions, but for a sensitive operation, this is strong.

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 each sentence carries substantive information: the core action, the canonical use case, the secret's handling, default expiry, and revocation path. It is front-loaded with the action and purpose, and while longer than ideal, the detail is necessary for a security-sensitive tool. There is some redundancy (repeating the 6-month default rationale), but overall it is structured well, with the most critical safety information (the secret not being exposed) stated early.

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 complexity of the tool (5 parameters, one required, security-sensitive, no output schema), the description is quite complete. It explains the use case, the authentication flow, the secret's handling, default expiry, and revocation. The lack of an output schema is compensated by describing the reply's contents (connection name and lease shape) and its exclusions (secret value). It doesn't cover potential errors or authentication prerequisites (like having a connection), but given the sibling context and schema descriptions, the essential info is present. A slight gap is not specifying how to set up the initial Microsoft connection, but that's covered by sibling tools like connections_accounts.

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 description coverage is 100%, so the schema already documents all five parameters with descriptions. The tool description adds context for appId (specifically for signing, the app with the Artifact Signing Certificate Profile Signer role) and for lifetimeMonths (explaining why default is 6 months). However, it doesn't add extra semantics for instance, displayName, or instanceName beyond what the schema provides. Since coverage is complete, a baseline of 3 is appropriate, with the added context on appId providing slight additional value, but not enough to push 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 clearly states the tool's purpose: mint a client secret for an app registration and vault it, with a specific verb ('mint', 'vault') and resource ('app registration'). It distinguishes itself from siblings like connections_lease_credential by emphasizing the one-step server-side process and the fact that the secret is vaulted without exposing the value. The context of Azure Artifact Signing provides a concrete use case, making the purpose 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?

The description explicitly describes when to use this tool (when a machine needs to authenticate as an app without human credential handling) and when not to (e.g., mentions revoking with graph_remove_application_password for early expiry). It also names the alternative tool for revocation, providing clear guidance on lifecycle management. The use case of Azure Artifact Signing is detailed, including environment variable usage, which helps an agent decide if this is the right 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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description goes further by stating 'no side effects' and detailing that failed sections return {error, detail} instead of silently disappearing. This adds meaningful behavioral context beyond 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 somewhat lengthy but well-structured, listing distinct output sections and next actions in a scannable format. Every sentence adds relevant detail, though some repetition (e.g., 'read-only, unmetered, no side effects') could be trimmed without loss.

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 thoroughly enumerates the returned sections (identity, deals, counts, next_actions, voice) and explains error behavior. This is sufficient for an agent to understand what the tool returns and how to interpret partial failures, making it complete in context.

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

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

The tool has no parameters, and the description accurately reflects that by specifying no input expectations. The baseline of 4 for zero-parameter tools applies, and there is no missing parameter information to penalize.

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

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

Clearly identifies itself as a session opener that returns identity, deal summaries, and recommended next actions, distinguishing it from the more focused connections_whoami and connections_execute siblings. The verb 'returns' and the explicit content list make its purpose 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?

Explicitly states it is the session opener and provides a ranked next_actions list with exact execute calls, guiding the agent to use it at the start of a session and follow up appropriately. Also notes it is read-only and unmetered, so the agent knows it can be safely called without side effects.

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?

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?

The description discloses the permanent effect (all tools stop working until reconnect), the ease of reconnecting (few clicks), and that the reply contains reconnect steps that must be read back verbatim. This goes beyond the annotations (readOnlyHint: false, destructiveHint: false, idempotentHint: true) and clarifies the impact without 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?

The description is detailed but every sentence carries essential information: the use case, the consequence, the confirm condition, the alternative tool, and the reply handling. It is front-loaded with the purpose and condition. It is slightly long but not verbose.

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

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

For a single-parameter tool with a simple schema and no output schema, the description covers all necessary aspects: when to use it, what it does, what happens after, how to confirm, and the alternative. An agent has everything needed to call it correctly.

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

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

The schema already documents `confirm` as a required boolean with a description, but the tool description adds the crucial condition that it must only be set after the member confirms in words. This enriches the parameter's meaning beyond the schema's basic 'Must be true.'

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 ends the connection's session ('Ends this connection's Connections session for good') and explicitly ties it to the scenario of the member being signed in as the wrong account. It distinguishes itself from connections_switch_workspace, which is a sibling, making the purpose 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 explicitly says 'Use this ONLY when...' and gives the exact condition (wrong account, sign out or switch account). It also provides a clear exclusion: if only a different workspace is needed, use connections_switch_workspace instead. It further instructs when to set `confirm` (only after plain-word confirmation).

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?

Describes return format and error behavior (unrecognized id, unbound connection), complementing the read-only annotation.

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, clear and to the point, though slightly repetitive with 'search' and 'fetch'.

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?

Includes output format and error handling, sufficient for the simple parameter set.

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?

Adds detail that id can be 'deal:<id>' or 'note:<id>' and that it comes from search, going beyond the schema's minimal description.

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

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

Clearly states the tool resolves an id (from search) to a full record, and distinguishes it from search by noting it is for clients that only speak search/fetch.

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 context that it is for ids returned by search and mentions the error case, but does not explicitly contrast with sibling tools beyond that.

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 the conditional inclusion of notes (once bound to a company), the maximum return count (10 of each), the output shape ({results: [{id, title, url}]}), and that each id can be used with fetch. This goes beyond the read-only annotation to explain actual 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 concise, with no filler. It front-loads the primary purpose, then provides return details and usage context in a logical order. Each sentence contributes distinct information, and the structure is easy to parse.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers all essential aspects: the search scope, conditional notes, return limit, result format, round-trip capability, and the intended client environment. Nothing needed for correct usage 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 only parameter 'query' has a schema description of 'Plain-text search terms' and the tool description repeats exactly the same phrase. Since the description adds no additional meaning beyond the schema, 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 action (search), the resource (Deal Flow marketplace deals and member notes), and the filtering condition. It also differentiates from other tools by indicating it targets clients that only speak search/fetch, making its purpose 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?

The description explicitly specifies when to use this tool: for clients limited to search/fetch interactions, and contrasts it with connections_pulse and connections_execute for full native tool access. This provides clear contextual guidance for selection.

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