Connections

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

Annotations only cover readOnly/openWorld; the description goes far beyond by disclosing the two row kinds (normal vs kind:'brokered'), that brokered credentials live in another plane named in `via`, that `callWith` determines how to call, and that a `brokeredUnavailable` field means the list is incomplete and must never be read as 'not connected'. That last point is a genuine correctness guard an agent could not infer.

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

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

Front-loaded with the core answer and the execute hand-off before the nuance. It is a dense single block and the Stripe brokered-vs-normal explanation is repeated in slightly different words ('read the row's kind before choosing how to call it'), but nearly every clause carries operational consequence.

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 burden of describing the return shape, and it does: service, instance, accountId, region, kind, via, callWith, brokeredUnavailable. Combined with the incompleteness warning, an agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `match` is for isolating one plane's instance because the full list is ~50 rows, and `service` is a slug filter that composes with match. It says nothing about `person` or `project`, but those are fully documented in the schema.

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

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

Opens with a concrete framing ('THE answer to is <service> connected?') and then states exactly what is returned: every connected account/instance with service, instance, accountId and region. It is unmistakably distinct from siblings like connections_apps or connections_execute, and even names the hand-off relationship to connections_execute.

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 ('is <service> connected?'), how to narrow ('looking for one plane's instance? pass match'), the scale rationale (~50 rows), and the downstream action (pass an instance as connections_execute's `instance`). It also gives a critical exclusion: Stripe accounts brokered through Pay must be reached with Pay endpoints, not service:'stripe'.

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 readOnly/no-destructive annotations it discloses the useful edge case: install_url is null while status is coming_soon, and the agent must never fabricate a store link. It also explains the `say` field is member-facing output to hand over as-is. The closing 'Read-only, no side effects' duplicates the annotations, which costs it a point.

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 what is offered, then the return shape, then the null-install_url caveat — a sensible order with no filler sentences. Only the redundant 'Read-only, no side effects' clause fails to earn its place.

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

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

With no output schema, the description does the work of describing the return payload (name, browser, status, install_url, summary, highlights, `say`) and the one null case. That is sufficient for a zero-required-parameter read tool; only the relationship to sibling tooling is unaddressed.

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

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

Schema description coverage is 100% and both parameters (`person`, `project`) are documented in the schema with omit-defaults explained. The description adds nothing about them, so the baseline 3 applies — the schema carries the burden entirely.

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?

It names the concrete resource (the Chrome add-ons for Connections Email, Connections Schedule and Notes) and enumerates the fields returned, so an agent knows exactly what this retrieves. It doesn't explicitly contrast with near-neighbours like connections_explore_connectors or connections_mcp_servers, which keeps it short of a 5.

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

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

Usage is implied rather than stated: an agent infers this answers 'what add-ons exist outside the chat'. It does give one concrete handling rule — pass `say` to the member verbatim and say 'coming soon' when install_url is null — but there is no explicit when-to-use/when-not or named alternative among the many sibling 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?

Annotations already declare destructiveHint=false and openWorldHint=false, so the description's real contribution is the visibility model — the event lands on the member's own Connections calendar, shown only to them — plus the default one-hour end and the all_day semantics. It does not warn that the operation is non-idempotent (annotations say idempotentHint=false), so a retry could silently double-book; that is the one gap keeping it below 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-loaded with the trigger and the sibling routing, then the format rules. Efficient overall, though the long first sentence and the repeated restatement of starts_at formatting that the schema already covers cost it a point.

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 tells the agent the reply names what was added and when, and instructs it to say that back. Combined with the visibility model, the sibling routing and the date-format rules, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the property descriptions restate nearly the same format guidance (ISO with offset, plain wall-clock read in timezone, ends_at default, all_day midnight). The description adds a small amount (a worked example mapping -06:00 to US Central), but the schema does the heavy lifting, so the baseline 3 applies.

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

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

States a specific verb and resource (create one calendar event on the member's own calendar) and immediately scopes it against siblings: public events with tickets go to connections_event_create, untimed to-dos to connections_todo_add. An agent can distinguish it from connections_calendar_update or connections_event_create without opening a schema.

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

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

Gives explicit trigger phrases ('add it to my calendar', 'block out 2-4pm tomorrow') plus two named alternatives with the exact conditions that select them (public event with page/tickets/RSVPs, or untimed to-do). When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already flag destructiveHint=true and non-idempotent, and the description goes well beyond them: removal is into the member's Trash (soft delete, recoverable), only self-added events can be removed, events inserted by another source are removed at that source, and public hosted events are out of scope. That is material behavioral context an agent cannot infer from annotations.

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

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

Front-loaded with the trigger condition and the single-event scope, then the safety protocol, then exclusions — a sensible ordering. The prose is dense and nearly every clause carries information, though one clause ('one another source put on the calendar') is garbled and slightly slows parsing.

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, no-output-schema mutation, the description covers what is removed, where it goes (Trash), which events are eligible, and the confirmation protocol. It stops short of saying what the call returns or how to undo the deletion beyond the Trash reference, which is a minor remaining 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 coverage is 100%, so the schema already documents id, person, dry_run and project, including the 'do this first' note on dry_run. The description reinforces the dry_run-first sequence and the id provenance but adds no new format or edge-case detail for person/project. 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 set (cancel/delete/remove) against a specific resource (one event on the member's own Connections calendar), and explicitly scopes to a single event by id into the member's Trash. It also carves out what it is not: not a reschedule (connections_calendar_update) and not a public hosted event cancellation.

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

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

Gives concrete trigger utterances ('cancel my 3pm', 'take lunch with Sam off my calendar'), names the prerequisite source for the id (connections_calendar_list), and routes the time-change case to connections_calendar_update. It also mandates a dry_run-first confirmation workflow, which is exactly the operational guidance an agent needs.

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/openWorldHint/destructiveHint=false, and the description still adds substantial context beyond them: the merged-source behavior (hosted events, note deadlines, a linked Google Calendar appear alongside native events), the ordering guarantee ('soonest first'), and the returned field set. It also discloses the window defaults and the 62-day cap, which shapes how the agent should scope queries.

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 ordered sensibly: when to use, what comes back, then the window mechanics. The final sentence largely restates defaults already present in the schema, which is mild redundancy, but every sentence is front-loaded and readable.

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 burden of describing return values, and it does so precisely (id, title, starts_at, ends_at, all_day, source) while also covering merge behavior, ordering, and window bounds. An agent has everything needed to call this correctly and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining how `from` and `days` compose into a single window and restating the defaults/cap in prose for quick reference. It adds nothing about the delegation parameters `person` and `project`, whose semantics come only from the schema.

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

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

States a specific verb and resource — 'Returns the events on the member's own Connections calendar in a window, soonest first' — and explicitly enumerates the merged sources (their own additions, hosted events, note deadlines, connected Google Calendar). This is clearly distinguishable from sibling write tools like connections_calendar_add/update/delete and from the broader connections_events_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 opening clause gives concrete trigger questions ('what is on their calendar', 'whether they are free or busy', 'today, tomorrow or this week') and adds a routing instruction to answer from this list rather than chat history. It does not name alternatives such as connections_events_list or connections_schedule_get_focus_day, so there is no explicit when-not guidance, but the intended use case is unambiguous.

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

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

Goes well past the annotations: it discloses partial-update semantics ('only the fields you pass change'), the both-starts_at-and-ends_at requirement to preserve duration, an ownership constraint (only member-added events; externally sourced events must be changed at the source), and the dry_run preview-and-confirm protocol. These are non-obvious behaviors an agent would otherwise get wrong, and none of them are recoverable from destructiveHint/idempotentHint alone.

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 triggering condition, then prerequisites, then the safety protocol, then exclusions — a sensible order with no filler sentences. It runs long as a single dense block, and the clause about events from another source is grammatically awkward ('one another source put on the calendar'), which slightly slows parsing.

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 9-parameter mutation tool with no output schema, the description covers the missing pieces: id provenance, partial-update behavior, coupled time parameters, ownership limits, and the dry-run/confirm loop. An agent can call this correctly without consulting anything else.

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 earns above that by explaining the omit-to-leave-unchanged convention across fields and the coupled relationship between starts_at and ends_at that the schema does not express. It does not, however, discuss timezone interaction with starts_at beyond what the schema already says.

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

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

States a specific verb and resource ('move, reschedule, push back, shorten, extend or rename an event on their own Connections calendar') with concrete utterance examples, and explicitly scopes it to ONE event by id. It is immediately distinguishable from connections_calendar_add and connections_calendar_delete, both named in the text.

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

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

Gives explicit when-to-use triggers in the member's own words, names the two sibling alternatives it is not (add, delete), states the prerequisite for obtaining the id (connections_calendar_list), and prescribes a mandatory dry_run-first workflow with member confirmation. Nothing about selection is left to inference.

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

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

Annotations already flag this as a destructive write (readOnlyHint=false, destructiveHint=true). The description adds useful behavioral context beyond that: it is a one-time operation that only works while the connection has no workspace, and it advises confirming with the member first. It does not explain what exactly makes the operation destructive or what happens on a failed attempt, which keeps it from 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?

The description is three tight sentences, front-loading the purpose and scope before the condition and the parameter hint. Every sentence adds distinct value with no redundancy.

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

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

For a mutation tool with full annotation coverage and a fully described input schema, the description supplies all the missing operational context: the triggering condition, the need to confirm with the member, the alternative sibling for the already-bound case, and where to source the company value. With no output schema, no return-value explanation is needed.

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 three parameters in detail. The description adds little beyond the schema for `company` and introduces a slight mismatch ('exact workspace name' vs. the schema's 'exact company name'), while the optional `person` and `project` parameters are not mentioned. Baseline 3 is appropriate because 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?

The description states a specific verb and resource: 'Put this connection into one of the member's own workspaces when it is not in any yet.' It distinguishes itself from the sibling `connections_switch_workspace` by clarifying the one-time condition, so an agent can tell the two apart without opening schemas.

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

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

It gives explicit when-to-use criteria ('when it is not in any yet, connections_whoami shows company:null') and names the alternative for the opposite case ('once it has one, connections_switch_workspace moves it'). It also prescribes a confirmation step with the member, leaving no inference about the right 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 the persistence side effect (every Cloudflare call and deploy defaults to the chosen account), that the list is always readable, and that no token is ever returned. It does not explain why destructiveHint=true is set or what auth/permission requirements the choose action carries, leaving a small gap. There is no contradiction with 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 trigger condition is front-loaded and the list-then-choose loop follows in logical order with no filler sentences. It is a dense run-on paragraph however, and the switching/fallback sentence could be tighter.

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 6-parameter, zero-required tool with no output schema, the description explains what 'list' yields (account names, the ones already chosen, needsChoice) and that tokens are excluded, which is the core decision loop an agent needs. It omits what 'choose' returns and when to set person/project/instance, so it is strong but not exhaustive.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it establishes 'list' as the default action, introduces the needsChoice signal that gates the use of accountId/accountIds, and frames accountIds as the plural form of accountId. The person, project, and instance parameters are covered only by the schema, not the prose.

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

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

The description names a specific verb sequence (list, then choose) on a specific resource (the Cloudflare account used by this workspace), and the title states the intent plainly. It is clearly separable from the deploy/other Cloudflare sibling tools because the selection gate ('more than one account', 'needsChoice') is spelled out.

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

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

It states the trigger condition (a Cloudflare connection reaching more than one account, OAuth picker with several ticked), the branch behavior for 'list' as the default, and the exact next step when needsChoice is true: ask the member, then call 'choose' with accountId or accountIds. It also tells the agent what to expect when the user asks for a different account ('answers with how to add that account').

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

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

Goes well past the annotations, which only mark this as destructive and open-world: it discloses that the ticket is single-use, expires in minutes (default 10, max 15), is bound to one account and one script, and grants nothing else. It also describes the downstream effect (server-side create/update that inherits existing bindings), the response shape (URL plus curl recipe, live workers.dev URL), and the ~5 MB base64 ceiling.

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 use condition and the never-ask-for-login rule, and every sentence carries operational content rather than filler. It is dense and long for a tool description, with the flow details packed into a single run-on middle section, which slightly hurts scanability.

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

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

For a two-step flow with no output schema, the description covers what an agent needs end to end: prerequisites (remote MCP only), credential sourcing, ticket lifetime and limits, how to build and POST the bundle, and what comes back. 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%, so the baseline is 3; the description still adds routing value by naming connections_accounts { service: 'cloudflare' } as the way to obtain accountId, restating the scriptName-or-pagesProject exclusivity, and confirming the ttl ceiling of 15 minutes. It does not add much on person, project, or instance, which is the only shortfall.

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

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

States a precise verb and resource — mints a ONE-TIME deploy ticket bound to one account plus one Worker script or Pages project — and names exactly which deployment shapes it covers (wrangler deploy, static site upload, Worker with assets, Pages build). It explicitly separates itself from the local cloudflare_deploy tool, so an agent can pick between them without opening either schema.

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

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

Gives an explicit trigger condition ('this chat has only the remote Connections MCP, no local tools') and an explicit exclusion with the alternative named ('with local tools use the local cloudflare_deploy tool instead'). It also rules out a wrong action the agent might otherwise take: never ask the human for a wrangler login or API token.

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 flag this as non-readOnly, destructive and open-world, so the safety profile is pre-declared. The description goes beyond that with concrete behavior: single-use state, 10-minute expiry, credential lands in the company vault via provider callback rather than the conversation, a 409 target_required path, and a landsOn field in the reply. That is substantive added context.

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

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

Front-loaded with the core action and return shape before the edge-case routing rules, so the important part lands first. It is dense and em-dash-packed, and a clause or two (e.g. the provider sign-in caveat) could be trimmed, but nearly every sentence carries operational information.

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

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

For a 9-parameter mutation with no output schema, the description supplies the return shape ({url, expiresAt}), the lifetime and single-use constraint, the 409 failure mode, and who must be authenticated (the human, at the provider, not here). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics on top: the precedence and purpose of reconnectId vs instanceName, the exact condition that justifies newConnection, and the error payload shape listing instanceName, reconnectId and accountName. Minor parameters (person, install, directory, environment) are left to the schema, which 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?

States a specific verb and artifact: 'Mint the provider's authorize URL for an OAuth connector,' and names concrete services (google_cloud, microsoft, cloudflare, discord, github). This is clearly distinguishable from siblings like connections_apps or connections_explore_connectors, which inspect rather than mint links.

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

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

Gives explicit routing rules: pass reconnectId or instanceName to re-consent an exact row, pass newConnection:true only to add another account, and expect a 409 target_required when live connections exist and neither is supplied. It also explains why re-consent is needed (a scope added to a connector never widens an existing grant), which is genuine when-and-why guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the description's real contribution is edge-case behavior: it explains what happens when the target is not on Connections ("says there is no path") and when names are ambiguous ("several name matches are all returned"). The explicit "requests no introduction" clause usefully confirms no side effect is triggered, though cost/pagination behavior is unstated.

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

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

Four tight sentences with no filler, front-loading the core capability before the trigger and the edge cases. The usage sentence overlaps slightly with the opening but is short enough not to be waste.

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

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

For a read-only lookup with no output schema, the description covers what matters for correct invocation: scope, ranking, ambiguity handling, and the empty-result case. It leaves the shape of a returned path (fields per connection) unspecified, which is acceptable given no output schema exists.

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 all four parameters are already documented; baseline is 3. The description adds a little meaning, notably that results are ordered warmest-first (which gives 'limit' a meaningful sort order) and that 'name' may match several people, but it never mentions the 'person' or 'project' scoping 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?

States a specific verb and resource (find who could introduce them to one named person) plus the mechanism (mutual connections) and the ranking rule (warmest first by recency and frequency). An agent can distinguish this from connections_contacts_request_introduction without opening either schema.

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

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

Gives an explicit trigger: "Call this when they ask who can introduce them to someone." It also implicitly routes away from the write-side sibling by noting "it requests no introduction," though it never names connections_contacts_request_introduction as the alternative for actually sending a request.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the trailing 'Read-only' adds nothing. However, the warning that a false `hasHistory` means the digest never flagged anyone and the counts are not a real zero is a genuine, non-obvious data trap that prevents misreading a zero as a real result. What is missing is any sense of the time window ('recently') or the exact response shape, which matters since there is no output schema.

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

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

The definition is front-loaded with the outcome summary and the caveat follows logically. The only waste is the redundant 'Read-only' sentence already covered by annotations, and the vague adverb 'recently' which does not pin down a window.

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-required-parameter aggregate with no output schema, the description does provide the measure list and the hasHistory caveat, which covers the essentials. It still leaves the time window, output format, and its relationship to overlapping follow-up siblings unexplained, so it is only adequate rather than complete.

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

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

Schema coverage is 100%, so `person` and `project` are fully documented in the schema itself. The description says nothing about how those parameters affect the scorecard scope, so it adds no meaning beyond structured data - 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 names the resource (a follow-up scorecard over people the product surfaced) and enumerates the three measures returned: flagged count, contacted count, and who is still waiting. It is clear what the tool reports, but it never distinguishes itself from near-neighbors like connections_contacts_overdue_followups or connections_contacts_who_to_follow_up_with, which an agent could easily confuse it with.

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?

There is no explicit when-to-use guidance and no named alternatives, despite the sibling list containing several overlapping follow-up tools. An agent must infer from the title alone that this is the 'progress summary' view rather than the 'who should I contact next' view.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds real behavioral context beyond that: the full field set returned and that timeline touches come by default, with include_timeline=false skipping a second read — a useful cost/latency hint.

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

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

Three sentences, front-loaded with the usage trigger, then the id source, then the return shape. No redundant restatement of the name or title and nothing that does not inform the call.

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

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

A read-only single-record tool with full annotation coverage and no output schema; the description lists the returned field groups and the default timeline behavior, which is everything an agent needs to call it 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 description coverage is 100%, so the schema already documents id, person, project, timeline_limit and include_timeline, and the description mostly echoes that the id comes from connections_contacts_list. Baseline 3 applies since 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 ('details about one specific contact') plus the scope of what is returned (full record + recent touches). This clearly separates it from list/search-style siblings because it is explicitly single-record and id-driven.

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

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

Gives an explicit trigger ('Use this when the member asks for details about one specific contact') and a prerequisite ('Pass the `id` from connections_contacts_list'), which routes the agent correctly for discovery-then-fetch. It stops short of excluding near neighbors in the large contacts family (e.g. connections_contacts_recent_interactions or connections_intel_about_person), so a small ambiguity remains.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the bar is lower, yet the description still adds real behavioral content: matching by email or phone updates the existing contact instead of duplicating, and the response reports created/updated/skipped counts. It does not disclose which fields get overwritten on a matched update, which matters for a destructive-flagged tool.

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

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

Four short sentences, front-loaded with the action and scope, then the required-field rule, then the dedupe behavior, then the response and limits. No filler and nothing buried.

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

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

With no output schema, the description usefully states the return shape (created/updated/skipped counts) and the batch ceiling. For a destructive-flagged bulk mutation the only meaningful gap is not saying what happens to existing fields on a matched contact update.

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 five parameters including nested contact fields. The description adds one genuine constraint not in the schema (200-person cap) and confirms the required-name rule, but says nothing about source, project, person, or dry_run beyond what the schema states. 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?

"Save SEVERAL people ... in one call" gives a specific verb (save), resource (contacts), and batch scope, which cleanly separates it from the single-record sibling connections_contacts_save_contact without needing to name it. The emphasized SEVERAL plus "one call" makes the batch nature 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 clear operative conditions: each person needs a name, the rest is optional, up to 200 per call, and "it looks up nothing" signals this is a write path, not a lookup path (so an agent needing to find someone should use a resolve/find tool instead). It stops short of explicitly naming alternatives or stating 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?

Annotations already declare a read-only, non-destructive, closed-world read. The description adds genuine behavioral context beyond that: result ordering ('newest-updated first') and the exact default field set returned. It doesn't mention paging limits beyond what the schema states or whether totals are returned, so it stops short of a 5.

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

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

Front-loaded with the usage trigger, then the return shape and ordering, then the two most useful parameters, then the sibling handoff. Every sentence carries information 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?

For a ten-parameter list tool with no output schema, the description covers the return fields and ordering well enough to call it confidently. Minor gaps remain around pagination/total-count behavior and the scoping parameters (person, project), which the schema covers but the description never frames.

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 ten parameters, including the scored-word query behavior and the compact/full enum. The description restates the query and needs_follow_up usage but adds no syntax or interaction detail beyond the schema, so the baseline 3 applies.

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

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

States a concrete verb+resource ('Returns the member's own Connections contacts') and enumerates the returned fields. The trigger phrasing (contacts, who they know, network, people met, follow-up) makes it clearly distinguishable from single-record siblings like connections_contacts_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?

Gives explicit user-intent triggers and routes the single-record case to connections_contacts_get {id}. It does not, however, distinguish itself from heavily overlapping siblings such as connections_contacts_who_to_follow_up_with, connections_contacts_overdue_followups, or connections_contacts_gone_quiet, even though 'who needs following up' is listed as a trigger.

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

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

Goes well beyond the annotations: discloses that exactly one note is appended, that it is dated now unless occurred_at is supplied, that an ambiguous name writes nothing and returns candidates, that it returns the recorded touch, and that contacts:write scope is required. These are exactly the failure modes and permission requirements an agent needs before calling a write tool.

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

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

Front-loads the trigger before the mechanics, and each sentence carries distinct information (trigger, parameter routing, write semantics, ambiguity, scope). Slight redundancy with the schema on id/email disambiguation keeps it off 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?

For an 8-parameter, single-required write tool with no output schema, the description covers the return value, the ambiguous-match behavior, the default timestamp, and the required scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the id-from-list and name/email disambiguation rules and the occurred_at default, adding only marginal meaning. Baseline 3 applies — it does not explain person, project, or channel beyond the schema.

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

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

States a specific verb and resource — adds one dated note to a contact's timeline — and grounds it in the member's own phrasing ("log a coffee with Sam"). The scope line "only ever writes to the member's own contacts" separates it from the broader note and people tools 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?

"Use this when the member says they talked to, met or called someone and wants it kept on that person's record" is an explicit trigger, and it names connections_contacts_list as the place to get the id. It stops short of saying when to prefer connections_note_save or connections_intel_remember_about_person instead, so there is no exclusion set.

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 real value beyond them: newest-first ordering, the fact that emails are included as a `kind`, the email payload fields (subject, direction, snippet, gmailThreadId), and the explicit 'empty result means nothing was recorded' contract.

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

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

Four short sentences, front-loaded with the core action, then the usage cue, then the email detail and the empty-result contract. Every sentence carries information; the phrase 'with what each one was and when' is slightly vague but still functional.

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, so the description must carry the return-value burden and it largely does (ordering, email kind and fields, empty-result behavior). The schema covers the limit default/maximum, so the remaining gap is minor, but per-contact vs cross-contact result shape could be clearer.

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 `name`, `limit`, `person` and `project` are already documented in structured fields; baseline 3 applies. The description adds only that `name` is a single contact and that results are 'logged by this member', but says nothing extra about `person` or `project` 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?

Uses a specific verb and resource: 'Return the most recent conversations this member logged with one named contact, newest first.' It even signals ordering and scope. It falls short of a 5 because it never names the adjacent tools it differs from (e.g. connections_message_read_messages, connections_contacts_get), leaving the agent to infer the boundary.

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?

'Call this for what they last discussed or emailed with someone' gives a clear situational trigger. There is no when-not guidance and no alternative tool is named, so the agent gets context but must infer exclusions against the many other contacts_* siblings.

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, and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses multi-match behavior on ambiguous names and clarifies that 'unscored' means never scored rather than zero — a semantic trap it proactively disarms. It stops short of describing no-match behavior or the response shape.

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

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

Three short sentences, front-loaded with the core result and the possible values, then ambiguity behavior, then the 'unscored' caveat. Every clause carries information an agent would otherwise get wrong; nothing is padding.

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

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

For a 3-parameter read tool with full schema coverage and no output schema, the description covers what is returned (strength tier plus last interaction) and two key edge cases. Only the no-match/empty-result case is left unstated, a minor gap against a tool of this simplicity.

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 input schema already explains 'name', 'person', and 'project' fully — baseline 3 applies. The description reinforces that the lookup takes exactly one contact name and tolerates ambiguity, but adds nothing about the run-as 'person' or workspace 'project' parameters beyond the schema.

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

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

States a specific verb and resource — report the tie strength between a member and one named contact — and enumerates the possible outputs (none, light, moderate, strong) plus the last-interaction timestamp. It does not distinguish itself from adjacent siblings such as connections_contacts_followup_scorecard, connections_contacts_recent_interactions, or connections_contacts_gone_quiet, so an agent must infer the boundary.

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?

There is no explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The only directional signals are behavioral ('returns every match when the name is ambiguous') rather than selection guidance, so the agent must guess why it would pick this over the other relationship-scoring 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?

Goes well beyond the annotations by disclosing the consent gate: the contact is notified, decides whether to proceed, and nothing reaches the sought person until they agree, plus the request sits in a 'pending' state. That explains openWorldHint concretely. It does not reconcile destructiveHint=true — no mention that the notification can't be unsent, whether the request can be withdrawn, or whether duplicate requests are blocked.

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 front-loaded sentences: purpose, then behavior, then trigger — nothing is buried. Slight redundancy between 'Ask one of the member's own contacts to introduce the member to someone' and the final trigger sentence, but it is minor.

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

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

For a 7-parameter mutation with no output schema, the description covers the core mechanics (pending request, notification, recipient consent) adequately, and the schema documents every parameter. It stops short of describing what a successful call returns (a request id, a confirmation message) or how the request can be cancelled.

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 applies. The description reinforces the meaning of broker_contact_id ('member's own contacts') but says nothing about target_contact_id, request_note, person, project, or dry_run, so it adds only marginal semantics over the schema.

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

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

States a specific verb and resource: asking one of the member's own contacts to make an introduction by creating a pending request. The scope ('member's own contacts', 'pending') clearly separates it from discovery-style siblings such as connections_contacts_find_warm_path, though no sibling is named explicitly.

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

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

The closing sentence gives an explicit trigger: 'Call this when the member asks a named contact for an introduction,' which makes the invocation context unambiguous. There is no when-not guidance, no named alternative (e.g. use find_warm_path first to pick who to ask), and no prerequisite about resolving contact ids.

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 readOnlyHint annotation, the description defines the four outcome values, says what `matchedOn` and `contact`/`candidates` hold, and flags the critical caveat that a 'none' result is only conclusive when `scanComplete` is true. That is genuine behavioral context an agent could not infer from annotations.

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

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

Front-loaded with the action and its scope, then the outcome vocabulary in a compact enumeration. Dense but every clause carries information; the trailing 'Read-only.' is the one redundant sentence given readOnlyHint=true.

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

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

There is no output schema, and the description covers the return contract (outcome values, contact, candidates, matchedOn, scanComplete) as well as the pre-action purpose. An agent has everything needed to call it 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 baseline applies; each parameter is already documented in the schema. The description reinforces that the `name` value can be a person, email or company, but adds no format or matching-rule detail beyond that.

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 object ('work out which ONE of this member's own contacts a name, email or company means') and scopes it to the member's own contacts. This clearly separates it from lookup siblings such as connections_contacts_get or connections_contacts_find_warm_path.

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?

'before acting on that person' gives an explicit trigger point, and the 'confirm' outcome tells the agent to go back to the member rather than proceed. No sibling is named as an alternative, so it stops short of full routing guidance.

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

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

Annotations already declare a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds real value by saying only member-supplied details are stored and that no lookup/enrichment happens, but it omits what the call returns, whether duplicates are created, and what the dry_run preview yields.

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

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

Two short sentences, front-loaded with the scope constraint, with no filler. The 'It looks up nothing' closer is a compact and high-value qualifier.

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 10-parameter but largely optional create operation with no output schema, the description covers the essentials: what is written, what is required, and that no resolution occurs. A note on duplicate handling or the returned contact would close the remaining 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 coverage is 100%, so the baseline is 3; the description goes slightly beyond by marking name as the sole required field and framing all other attributes as optional and member-supplied only. It does not explain the scoping parameters (person, project) or dry_run, which remain schema-only.

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 ('Save'), resource ('ONE new person') and scope ('to this member's own contacts'), plus which fields are required vs optional. This clearly separates it from siblings like connections_contacts_import_contacts, connections_contacts_resolve_contact, and connections_contacts_update_role.

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

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

Gives an explicit trigger ('when the member asks to add or remember someone') and a useful exclusion ('It looks up nothing'), which tells the agent not to expect resolution or enrichment. It stops short of naming the alternative tools to use for lookup/dedupe, so it is clear but not fully 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 already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), and the description adds real substance beyond them: how the suggestion is derived (median gap of logged conversations), that it also reports the currently set cadence, that ambiguous names return every match, and that a null suggestion means insufficient history. Only the exact form of the returned cadence and any per-account scoping remain unstated.

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

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

A single dense sentence front-loads the purpose, then layers derivation, output, ambiguity handling, and the null case in a logical order. No filler, no restatement of the title, and every clause carries information an agent needs.

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

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

With no output schema, the description carries the burden of describing returns and does so: a cadence suggestion, the current cadence, all matches on ambiguity, and null for insufficient history. It stops short of saying what unit or shape the suggested cadence takes, which is a minor but real gap for a tool whose whole output is that value.

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, and the description earns above that by explaining what 'partial names are fine' actually produces: multiple matches are returned when the name is ambiguous. It does not add anything about the 'person' or 'project' parameters, which the schema already documents adequately.

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 ('Suggest how often this member should check in with one named contact') and pins down the computation ('median gap between the conversations they have actually logged'), which is precise enough to separate it from adjacent tools like connections_contacts_followup_scorecard or connections_contacts_gone_quiet. No sibling tool is named explicitly, so the differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance: nothing says whether to reach for this versus connections_contacts_followup_scorecard, connections_contacts_who_to_follow_up_with, or connections_contacts_overdue_followups when a member asks about staying in touch. The scope implies a use case, but no prerequisites, exclusions, or alternatives are offered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'replaces the stored value', telling the agent that the previous title/company is overwritten rather than merged. It does not cover auth requirements, failure modes, or the dry_run preview path beyond what the schema states, so it is useful but not comprehensive.

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

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

Four short sentences, front-loaded with what it does, then when to use it, then overwrite behavior, then the minimum-input rule. No filler; slight redundancy between 'Update an existing contact's job title and/or company' and 'a new title or employer' is the only waste.

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 6-param mutation with no output schema, the description covers purpose, trigger, overwrite semantics, and the minimum required input, leaving the person/project/dry_run mechanics to a fully documented schema. It could say more about what a successful update returns or whether partial updates preserve untouched fields, but the essentials for correct invocation are present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a real constraint absent from the schema: 'Give at least one of title or company', which the JSON schema does not enforce (only contactId is required). That single sentence prevents a no-op call and earns above baseline.

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

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

States a specific verb and resource ('Update an existing contact's job title and/or company') and adds scope ('on this member's own contacts'). It explicitly separates itself from creation-oriented siblings with 'does not create contacts', so an agent can distinguish it from connections_contacts_save_contact without opening either schema.

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

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

Gives a clear triggering condition: call it when the member supplies a new title or employer for someone already in their contacts. It excludes the create case but never names a sibling alternative (e.g. save_contact, connections_contacts_get) explicitly, so routing is inferred rather than spelled out.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses that the copy SHARES the credential (nothing secret duplicated, read, or returned), describes the overwrite sequence (copy lands first, old row disconnected, copy takes the name), and enumerates the failure codes with their meanings. This is unusually rich mutation semantics for a destructive tool.

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

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

Front-loaded with the core action and the share-credential fact, then structured into naming rules, defaults, and overwrite. It is dense and long, but nearly every clause carries either a constraint or an error-handling instruction an agent needs; only the redundancy with the schema's exclusive-form wording is mild waste.

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

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

For an 8-parameter, destructive, cross-workspace tool with no output schema, the description covers authorization preconditions, source-naming resolution, ambiguity and not-found recovery, overwrite behavior, and even spells out the return shape {connectionId, projectId, instanceName, sharesCredential}. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the exactly-one-naming-form rule with its conflicting_source/missing_source consequences, fromProject's default and when to pass it (ambiguous_source), and overwrite's target-workspace requirement. It largely duplicates the built-in schema hints on connectionId/service/instance exclusivity, keeping 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+resource+scope: copy a connected service (Cloudflare, GitHub, AWS) from one member workspace into another, sharing the source credential. It also distinguishes itself from the sibling connections_copy_connection_link by naming that tool for the link-minting case.

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 (both workspaces must be the member's own) and when-not (cross_workspace_refused — say it and do not retry), and it routes the agent to connections_copy_connection_link when the member asked for a one-tap link. The error-driven alternatives (not_found, ambiguous_source) also tell the agent exactly what to do next.

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

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

Goes well beyond the destructiveHint=true annotation: the link is single-use, bound to the member's account, expires in 10 minutes, opens signed in as them, and confirms only on their tap. It also discloses that this call itself copies nothing and that the agent cannot confirm it, which frames where the destructive potential actually lives.

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 artifact and the routing decision, then behavior, then return value. Dense but every clause carries information; the only waste is restating connections_copy_connection's role twice.

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 supplies the return shape ({url, expiresAt}) and what to do with it (send the url to the member). For a non-idempotent, expiring, human-in-the-loop artifact, all decision-relevant facts are present.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds meaning by constraining toProject/workspace semantics ('both workspaces must be the member's own') and reinforcing that mode is copy-or-move, which the schema states more tersely.

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 artifact: mint a one-tap link that hands a copy (or move) of a connection between workspaces to the member. It explicitly distinguishes the artifact from the action, and names the sibling (connections_copy_connection) that performs the copy directly.

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 default ('call that first'), two named trigger conditions (member asks to confirm; connections_copy_connection returns cross_workspace_refused with a share-scope reason), and an exclusion (for a workspace shared to them, use connections_copy_connection). Nothing about routing 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?

Beyond annotations, it discloses live editing, version retention, linked-chart behavior, error states such as 'linked' and 'stale_version', ledger rows from turns, and brief replay after compact. These are substantial behavioral details an agent needs and none contradict 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?

It is front-loaded with the purpose and necessary for a 12-action, 20-parameter tool, but it is one dense paragraph with semicolon chains. The content earns its place, yet the structure makes it harder to scan than it could be.

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 multi-action tool with no output schema, it covers all actions, return statuses, versioning, linked workspaces, run answers/facts, and error cases. An agent has enough context to select the action and understand its behavior.

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 has 100% description coverage for all 20 parameters, including examples for answers, facts and ops. The description largely restates the action and parameter semantics from the schema rather than adding much meaning beyond it.

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

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

The description states the resource (a per-workspace decision flowchart) and its purpose: guiding an AI chat on delegation, sizing, routing and briefing. It is clear but does not explicitly differentiate itself from any sibling, though no sibling tool overlaps.

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

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

It gives a concrete trigger ('when an AI chat starts a task...') and some when-not guidance ('quick exits ... need no call'; most tasks end at myself). It does not name alternative tools or explicit exclusions beyond those 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 already declare non-read-only, idempotent, non-destructive, closed-world, and the description reinforces and extends that: an exact name creates nothing and returns the existing workspace, a close name returns candidates instead of writing, and a 402 signals a plan limit. These are consequential failure-mode details an agent could not infer from the schema or 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?

Purpose is front-loaded in the first clause, and each subsequent sentence handles a distinct case (near-match, exact match, 402, next step) with no filler. Dense but every sentence earns its place.

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

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

For a mutating tool with no output schema, the description covers the happy path, the two non-creating outcomes, the billing failure, and the required follow-up call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the workflow for confirm (ask the member first, then retry with confirm:true) and the distinction between close and exact name matches. It says less about person and project, which the schema already covers adequately.

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

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

States a specific verb and resource ("Create a new workspace on the signed-in account") with clear scope. It implicitly separates itself from connections_switch_workspace, which it names as the follow-up action rather than the creation 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?

Explicitly says when to call it ("when the member asks for one") and what to do in the tricky cases: near-duplicate name, exact-name match, and a 402 plan limit. It routes to the sibling tool (connections_switch_workspace) for the next step.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: create is idempotent and never mutates existing data, sql batches run as a single all-or-nothing transaction, reads cap at 1000 rows / 1 MB with a `truncated` flag, statements time out at 15 seconds, batches hold at most 50 statements, no passwords are ever returned, and audit is owner-restricted. These are exactly the operational guardrails an agent needs.

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

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

The description is long but well structured: purpose first, then usage trigger, then a compact action-by-action breakdown. A few clauses are redundant with the schema (e.g. restating the $1/$2 convention), but each sentence carries real information and none are 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 five-action database tool with 8 parameters and no output schema, the description covers everything an agent needs: how to create, how to inspect, how to query, limits on results and runtime, transaction semantics, and the audit action's access restriction. No meaningful gap remains.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description still adds value by explaining the mutual exclusivity of `sql` vs `statements` in behavioral terms (one statement vs a transactional migration batch) and by stating the parameter placeholder convention ($1, $2 with `params`) in context. The 50-statement batch cap is also surfaced, which the schema only partially implies.

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 resource (the workspace's own Postgres database) and enumerates the operations available through the action enum (create, status, tables, sql, audit). It clearly distinguishes this tool from siblings like connections_storage_* or connections_execute by scoping it to a dedicated relational database with specific extensions installed.

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: 'Call this when the member wants to store data for a project, create tables, save or read rows, or run a migration.' It also bounds the tool with 'It cannot reach any other database,' which implies when it is not applicable. There is no explicit named alternative for those cases, keeping it out of 5 territory.

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 provides rich behavioral context beyond annotations, detailing side effects like stopping public marketplace feeds, stopping boosts, and notifying saved members. It clearly defines the scope ('under scope 'mine'') and limitations (does not edit or delete).

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 tool definition is densely packed with information, but it is highly efficient. The structure is logical: definition -> finding ID -> mechanics -> required workflow -> limitations. Every sentence serves a critical, non-redundant purpose.

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 that this is a complex mutation tool with an operational workflow requirement, the definition is extremely complete. It covers the what, why, how, safety protocol, and boundary conditions, leaving the agent fully equipped to use 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?

Although schema coverage is 100%, the description adds value by explicitly stating that the `deal_id` must be sourced from `connections_deals_list` scope 'mine'. This adds necessary context to parameter usage that transcends basic schema definition.

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 defines the purpose: to 'close, wrap up or take down a deal.' Crucially, it distinguishes this function from `connections_deal_update` by focusing on status transition (setting it to 'closed') rather than modifying other attributes.

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 provides explicit 'when to use' guidance ('when the member asks to close, wrap up or take down a deal that is done'). Furthermore, it mandates a specific operational workflow: requiring the agent to use `dry_run` true first and confirm with the member before execution.

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

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

Goes well beyond the annotations: it warns that a live listing is visible to everyone on the marketplace, that publishing requires a paid plan (with the failure mode explained rather than just failing), that drafts work on any plan, and that dry_run previews the exact call. These are exactly the consequences an agent needs before making a destructive, non-idempotent, open-world call.

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?

Five short sentences, front-loaded with the trigger condition, then creation semantics, then plan gating, then the dry_run escape hatch. No filler and nothing repeated from the schema verbatim.

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 15-parameter mutation tool with no output schema, the description covers the high-stakes behaviors (live vs draft, paid plan, public exposure, dry run). It leaves the workspace/person scoping parameters and private-visibility flow unexplained, though those are self-documented in 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 coverage is 100%, so the baseline is 3; the description earns extra by explaining cross-parameter behavior the schema cannot: publish=true only goes live when title AND full_description are both present, and the plan gate applies only to live listings. It does not touch visibility/password pairing, but the schema already covers that.

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 ("Creates one deal") and enumerates the user intents that trigger it (post a deal, list a raise, sell a business, find a buyer/partner). This clearly separates it from the read-side siblings connections_deals_list and connections_deals_search.

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 "Use this when the member asks to..." trigger list and clarifies the publish-vs-draft decision point. It does not name the sibling tools (deals_list, deals_search) as alternatives, so an agent must still infer that reading deals is a different call.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the description only needs to add scope behavior — and it does: the feed is always active public listings, 'mine' spans every status including drafts, and the feed ranks free-text queries by relevance. It stops short of describing pagination limits or ordering of results outside of relevance ranking.

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 use-when clause, then scope behavior, then filters, then row contents, then the sibling pointer — a sensible order with little filler. The one sentence listing row fields is slightly listy but earns its place since there is no output schema.

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

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

For an 11-parameter read tool with no output schema, the description covers the selection criteria (which scope, which filters) and summarises the returned row shape (title, summary, category, region, capital sought, status, link). It leaves pagination and result ordering implicit, a minor gap given the fully documented schema.

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

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

Schema coverage is 100%, so the schema already documents limit, offset, detail, fields, person, project, status and the enums. The description reinforces the scope default and the category/region/query filters but adds no syntax or precedence detail (e.g. how 'fields' overrides 'detail') beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb (browse/list) and resource (deals/listings) and immediately names the two scopes it can return, so an agent can tell it apart from connections_deal_create or connections_deal_update 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?

Opens with an explicit trigger ('when the member asks about Deals... raises, or their own postings') and names the alternative for the adjacent task ('To post a new deal, use connections_deal_create'). It also spells out which scope to pick for public vs. own listings, which is the main routing decision.

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 flag destructiveHint=true and openWorldHint=true, and the description adds material context beyond them: it is a partial update (only supplied fields change), edits to a LIVE public listing are visible marketplace-wide, and a live edit is re-screened so the response may report it was held for review. That last point is exactly the kind of outcome an agent could not infer from annotations.

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

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

The routing condition and deal_id requirement are front-loaded, followed by partial-update semantics, then the live-listing risk, then the dry_run procedure, then exclusions. Every sentence supplies a distinct fact; nothing is restated from the name or schema.

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

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

For a 30-parameter destructive mutation with no output schema, the description covers the essentials: partial-update behavior, marketplace visibility, review-hold outcomes, and a safe preview workflow. It stops short of describing error cases (e.g. invalid deal_id, private visibility without password beyond the schema's note), which keeps it just under fully complete.

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

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

Schema description coverage is 100% across all 30 parameters, so the schema already explains each field, including the enum meanings and the visibility/password dependency. The description adds only workflow-level semantics for deal_id and dry_run; per the baseline rule, 3 is appropriate when the schema carries the parameter 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?

The description names a specific verb set (edit, change, fix, reprice) against a specific resource (one of the member's own deal listings) addressed by deal_id. It explicitly separates itself from connections_deal_create and connections_deal_close, so an agent can pick the right tool without opening any schema.

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

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

It states when to use it, how to obtain the required id (connections_deals_list scope 'mine'), the constraint that it only works on the member's own deals, and names the two alternatives it is not. It also prescribes a workflow: dry_run first, then confirm with the member before the real call.

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 destructive/idempotent annotations, it discloses consequences the annotations cannot: paid tickets are refunded, guests are NOT messaged (with a reminder to tell them), drafts are archived rather than canceled, canceled events remain in the list, and invalid targets return a plain message. This is exactly the side-effect detail an agent needs before a destructive call.

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 trigger condition and core behavior are front-loaded in the first two sentences, and every clause carries actionable information. It is dense and the final sentence bundles two alternatives (update-event and publish) in one line, which is slightly crowded but still parseable.

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 mutation with no output schema, the description covers the full picture: what happens to tickets, what happens to guests, what happens to drafts, what happens to the list entry, what a failed call looks like, and the confirm-before-commit protocol. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by prescribing the dry_run:true-first protocol and by tying event_id to 'the member's own event' found via connections_events_list. The person/project parameters are left to the schema, which is acceptable given full 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?

States a specific verb and resource ('cancel... one of their own hosted events by id') and immediately clarifies the dual behavior (cancel published vs archive draft). It explicitly distinguishes itself from connections_event_delete and connections_event_publish, so an agent can pick it apart from siblings without opening schemas.

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

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

Gives a concrete trigger ('cancel my meetup'), a mandatory two-step workflow (dry_run:true first, confirm, then real call), and explicit alternatives for adjacent intents (delete to remove, publish to put a draft live, update-event to edit a staying event). Exclusions are named: not-own, already-canceled, or archived events are rejected.

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

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

Adds substantial context beyond the annotations: it creates a DRAFT that is private until published, is free to create, lives in the connection's preferred workspace unless project overrides, does not touch the calendar, and consumes no Connections AI credits. The dry_run-first protocol is stated explicitly, which is the key behavioral instruction for a non-idempotent mutation.

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

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

Front-loaded with the trigger condition and the core action, then follows with exclusions, dry_run guidance, and follow-on calls in a logical order. It is dense and long for a single tool, but nearly every sentence carries routing or behavioral 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?

Covers what would trip an agent up on a non-idempotent create: draft vs live state, where the event lands, what it does not do (calendar), how to preview with dry_run, and how to complete the workflow via publish/settings tools. No output schema exists, but the description tells the agent what it gets back (an id used by publish).

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the workspace default for `project`, the authoring responsibility for title/description, the publish path that consumes the returned id, and the optional start/end fields' semantics. It does not restate the enum or the guest-visibility behavior, which is fine since the schema covers 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?

States a specific verb and resource ('Creates ONE hosted event... its own public page with RSVPs and tickets') and explicitly contrasts with the calendar tool and the settings-management sibling. An agent can distinguish this from connections_calendar_add, connections_event_publish, and events_manage_hosted_events 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 ('host an event', 'set up a meetup'), an explicit exclusion ('does not put anything on the member's own calendar... for add it to my calendar use connections_calendar_add'), and routes follow-on work (publish via connections_event_publish, other settings via events_manage_hosted_events).

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 destructiveHint annotation, the description explains that the event goes to Trash with its series dates and guest list, remains restorable by the same id while the plan allows, and only the owner can delete it. It also discloses that a published event's page stops working immediately and guests are not messaged, which is critical behavioral context for a destructive operation.

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 trigger and scope, then layers in restoration, ownership, ticket, cancellation, and dry-run details. It is appropriately dense for a destructive tool, though the dry_run instruction partially repeats the schema description.

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

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

With no output schema and only general annotations, the description fully carries the burden: it covers restoration, ownership restrictions, ticket constraints, guest notification behavior, page status effects, dry-run workflow, and multi-delete handling.

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 meaningful workflow semantics for dry_run (it names the event and guest count without deleting) and clarifies event_id as the member's own event, though it does not discuss person or project.

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: delete one of the member's own hosted events by id. It explicitly distinguishes this from related siblings such as connections_event_restore and connections_event_cancel, so an agent can identify the tool's exact scope.

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 concrete trigger phrases ('delete my test events', 'remove that draft') and clear exclusions: use cancel instead for real events people were coming to, and events with paid tickets must be canceled first. It also instructs calling dry_run:true first and confirms one-event-per-call behavior.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is known. The description adds real context beyond that: no emails/phone numbers/manage links are returned, it changes nothing, and non-owned events are 'turned back with a plain message'. It stops short of describing pagination/omission behavior in detail, though guests_limit in the schema covers the truncation note.

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

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

Front-loaded with the trigger condition and the return payload, then the negative boundaries and the sibling fallback. Dense but every clause carries information; the parenthetical example questions are slightly heavy but useful for matching agent queries.

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?

Complete for a read-only single-event getter: what it returns, what it deliberately omits, how to obtain the id, the fallback for listing, and the ownership failure mode. No output schema exists, but the description enumerates the return shape well enough for an agent to answer follow-up questions.

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 all four parameters are documented in the schema including the default-50/max-500 truncation semantics. The description adds only the pointer on getting event_id via connections_events_list, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (ONE hosted event by id) and enumerates exactly what comes back: settings, ticket tiers, registration questions, capacity, status, guest list. It is clearly distinguished from connections_events_list and from other event siblings like connections_event_cancel/publish/update.

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 phrasing ('how is my demo day set up', 'how many are coming to X'), names the alternative for listing multiple events (connections_events_list), and states the exclusion case: an event that is not the member's own is rejected. When-to-use, when-not, and how to find the required id are all 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?

Beyond annotations, it discloses cost behavior (0.05 credits once, free thereafter), what happens when credits are insufficient, the public visibility consequence, ownership restrictions, and the returned public URL. This adds substantial context to the destructive/open-world 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 front-loaded with the action and conditions, and most sentences carry useful operational detail. It is somewhat long and includes a tangential note about writing the title and description manually, but overall it is structured and not padded.

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

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

Although there is no output schema, the description states that the public event URL is returned. It also covers prerequisites, failure cases, cost, visibility, and the dry-run confirmation step, which is enough for an agent to invoke and explain 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?

Schema coverage is 100%, so parameter meanings are already well documented. The description reinforces event_id ownership and the dry_run-first confirmation flow, but most parameter semantics remain supplied by the schema rather than the 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?

The description uses a specific verb and resource: publishing one of the member's own draft hosted events, making its public page live and RSVP-enabled. It clearly distinguishes this from creating or updating an event and makes the outcome understandable 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?

It gives explicit triggers ('publish', 'go live with', 'open registration') and constraints: only the member's own draft, already-published or non-owned events are rejected. It also prescribes a dry-run-and-confirm workflow before real publishing.

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 (destructiveHint/idempotentHint true), it discloses exactly what comes back — same id, status, page, ticket tiers, questions, guest list, and every date of the series — plus the retention constraint tied to the member's plan and the no-op failure mode. That is real behavioral context an agent cannot get from the 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?

A single front-loaded paragraph that opens with the trigger condition and then layers restore fidelity and failure behavior. It is dense but every clause carries information; the parenthetical about plan-based Trash windows is the only slightly buried 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?

For a one-required-parameter mutation with no output schema, the description covers outcome, preconditions, and failure reporting well. Minor gap: dry_run's semantics (a preview that restores nothing) are left entirely to the schema, which is defensible but would be worth a phrase for a destructive operation.

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 provenance meaning for event_id (the value returned by connections_event_delete) but says nothing about dry_run, person, or project, leaving those to the schema.

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

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

States a specific verb and resource ('Brings the event back from Trash') and enumerates the trigger phrasings ('undo that', 'I deleted the wrong event'), which separates it cleanly from connections_event_delete and connections_storage_restore_from_trash.

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 conditions, names the sibling to consult for Trash state (connections_storage_list_trash), specifies which id to pass and where it came from (connections_event_delete), and states the when-not case: if the event is not in Trash or a resource like its web address was taken, nothing changes and it explains why.

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 real behavior: the live-only default (published + draft, never canceled/archived), the sort order in both upcoming modes, and the override rules for status. It doesn't discuss pagination limits or result caps beyond the `limit` schema, which keeps it 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-loaded with the trigger and the negative case in the first sentence, and the default/override logic follows logically. The second and third sentences are dense run-ons that could be split for scanability, but nothing is 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?

Nine optional parameters with no output schema, yet the description covers what each result contains, the default filter, sort order, and workspace scoping — everything needed to call it correctly. Remaining details (limit range, detail enum) are fully documented in 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 coverage is 100% so the baseline is a 3, but the description earns more by explaining the interaction between parameters the schema states individually: upcoming+no-status means live-only, status overrides that default, and project narrows to one workspace. The `query`, `detail`, and `fields` semantics are left entirely to the schema.

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

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

States a specific resource and scope: the member's hosted events across every workspace, soonest first, with the fields returned. It explicitly distinguishes itself from connections_calendar_list (own calendar) and connections_event_get (single event's guests/settings), so an agent can route 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?

Opens with the trigger condition ('when the member asks about the events they host...') and names both alternatives with their selecting condition. It also gives a worked example of the status filter ('status canceled for the called-off events'), leaving little 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 annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces that with concrete detail: the supplied text REPLACES existing content, so the event should be read first, and omitted fields are left untouched. That is meaningful operational context beyond the annotations, though it says nothing about permissions or the dry-run path beyond what the schema already documents.

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 verb and scope, then the required input provenance, then the replacement hazard. Every clause carries distinct information and nothing is repeated.

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 six-parameter destructive mutation with no output schema, the description covers the critical unknowns: where eventId comes from, how text replacement behaves, and what is out of scope. The only shortfall is that it does not state what the tool returns or how dry_run behaves, but the schema partially covers the latter.

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

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

With 100% schema coverage the baseline is 3, and the description earns more by explaining the replacement-not-patch semantics, the omit-to-preserve rule, and the source of eventId. It still leaves dry_run, person, and project semantics entirely to the schema, which is acceptable given the coverage.

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

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

The description states a specific verb ('Rewrite the words on') and a bounded resource (title, description, or both) on an event the member already has, which separates it from a general event mutation. It does not name the sibling that handles the excluded fields (date, price, capacity, publishing), so an agent must infer that another tool covers them.

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

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

It gives clear when-to-use context: wording only, get eventId from list_my_events, read the event first, and send full replacement text rather than a patch. It also carves out a negative scope by forbidding date/price/capacity/publishing changes, though it does not point to the tool that should handle those instead.

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 a destructive, idempotent, open-world write, and the description adds behavior well beyond that: patch semantics ('Changes only the fields you pass; every other setting, ticket tier and question stays as it is'), immediate public-page propagation, and the crucial fact that guests are NOT messaged — with an instruction to tell the member. That last point is exactly the kind of side-effect disclosure annotations cannot carry.

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

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

Front-loaded with the trigger condition and examples, then effects, then alternatives, then dry_run, then the ownership caveat — a logical escalation with little waste. Slightly long, and the trailing owner sentence could have been folded into the opening line.

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 mutation with no output schema, it covers the high-risk unknowns: partial update, guest notification gap, public visibility, ownership, and the dry_run safe path. It does not address boundary cases such as lowering capacity below current registrations or the effect of a reschedule on already-published invitations.

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 explains every parameter including dry_run, event_id, capacity null semantics and description replacement. The description reinforces a couple of these (capacity, description, partial update) but contributes no meaning the schema lacks, which is the baseline for full 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?

States a specific verb (change/edit) plus resource (one of the member's own hosted events) and enumerates the affected fields (name, time, place, description, capacity). It also explicitly separates itself from the publish/cancel/delete siblings, so an agent can route correctly 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?

Gives concrete trigger phrases ('move my meetup to Friday at 7', 'cap it at 50 people'), names the alternatives for other operations ('To publish, cancel or delete, use those tools instead'), and prescribes a call order: dry_run:true first, then the real change. It even states the ownership precondition.

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 substantive behavior: it discloses each result's fields (lanes, connected flag, page, connect_url, copyable_from), the design rule that unconnected endpoints are NOT searchable, and hard constraints — the agent cannot connect anything and must never ask a human to paste a credential.

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 purpose before the operational detail, and nearly every clause carries information. It is dense and slightly run-on in the connect_url/copyable_from section, but no sentence is filler.

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

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

With no output schema, the description takes on the burden of describing return values and does so fully (lanes, connected status, connect_url, copyable_from/copy_url). For a read-only registry lookup with fully documented params, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that query matches name OR purpose and that blank means the whole registry, which is behavior the schema only hints at. The connected and person/project parameters are left to the schema.

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

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

States a specific verb and resource: see the whole connector registry and which ones this workspace already holds, with concrete examples (Stripe, GitHub, Cloudflare). It is clearly distinguishable from connections_search_catalog (endpoint search) and connections_copy_connection (copying), so an agent can route without opening schemas.

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

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

Explicitly says when to use it (task needs a service that's missing), how to query it (pass a query or leave blank for everything), and names the alternatives: connections_search_catalog for connected endpoints, connections_copy_connection when both workspaces are the member's own, and hand over connect_url/copy_url otherwise.

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

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

Annotations already establish safe read-only, non-destructive, closed-world behavior. The description adds useful context about what comes back (required fields, optional fields, a runnable example, confirmation requirement) and the fallback to a full capability map. It does not, however, discuss matching strictness beyond 'matches nothing', confidence signals, or how ambiguous multiple matches are resolved beyond the `domain` nudge.

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

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

Front-loaded with the trigger condition, then the invocation pattern, then the fallback behavior. Dense but nearly every clause carries operational meaning; the parenthetical example list of intents is slightly long but illustrative.

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, so the description carries the return-value burden and does so fully: it names what the response contains when a match is found and what it contains when it is not. For a router tool with 7 optional params, this is complete enough to use correctly without probing.

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 still earns above baseline by explaining intent should be phrased in the member's own words with concrete examples, and by explaining the purpose of `domain` (disambiguating when intent alone is ambiguous, like 'add').

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: it resolves an intent into the one Connections tool to call, returning that tool's fields, example, and confirmation requirement. It clearly distinguishes itself from the ~90 sibling tools, which are the very tools it routes to.

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 says explicitly when to use it ('BEFORE guessing which Connections tool to call, or when unsure what Connections can do at all') and names the disambiguation mechanism via `domain`. It also covers the no-match/browse case, so an agent knows the fallback path without experimenting.

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, it discloses the merge semantics on existing people, the idempotency guarantee, the continuation protocol (runId + nextCursor when not finished), the returned fields, and the unconnected-account fallback that returns a connect link. The only mild tension is calling a destructiveHint=true operation 'safe', though the sentence is scoped to re-running rather than to overwriting.

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

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

Four tight sentences, front-loaded with the action and merge semantics before the pagination mechanics and the edge case. Dense but every sentence carries information; 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 correctly explains the return payload (run id, created/updated/skipped counts, finished flag) as well as the loop-termination condition and the no-account path. Remaining gaps are minor: dry_run behavior and what merging does to conflicting field values on existing contacts.

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 runId, cursor, person, dry_run, project and accountId are already documented in the schema. The description reinforces runId/cursor as the continuation pair and implies accountId defaults to the main account, but adds nothing about dry_run or project beyond what the schema says, so baseline 3 applies.

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

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

The first sentence names a specific verb and resource (import Google contacts into Connections contacts), and the 'Google' qualifier separates it from the generic sibling connections_contacts_import_contacts. It never names that sibling explicitly, so an agent must infer the distinction rather than being routed.

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 clear operational context: rerunning is safe because of merging, and an unfinished run must be continued by calling again with runId and nextCursor. It also states the behavior when no Google account is connected. It stops short of saying when to prefer this over the file-based import 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, destructiveHint=false and openWorldHint=false, so "Read-only" in the description is largely redundant. The genuinely additive part is the field-level description of what each run record contains (source, status with reason code, start/finish times, received/created/merged/skipped counts), which substitutes for the absent output schema. However, nothing is said about pagination beyond the limit default, or about behavior when no runs exist.

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

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

Three sentences, front-loaded with the resource and ordering, followed by return-content detail and then usage purpose. Every sentence carries information an agent would otherwise have to infer, and there is no filler.

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

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

With no output schema, the description usefully summarizes the shape of each returned run, and the three optional parameters are fully covered by the schema. The only missing piece is how this tool relates to the import-starting siblings when an agent is deciding between reading and initiating imports.

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 explains limit (default 20, max 100), person impersonation, and project workspace scoping. The description reinforces the ordering semantics of limit ("newest first") but adds nothing about the person or project parameters, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ("List the member's own contact import runs") and adds ordering ("newest first"), which clearly separates it from write-oriented siblings like connections_contacts_import_contacts or connections_import_google_contacts. It stops short of naming any sibling explicitly, so an agent must infer the read-vs-import boundary, but the scope is unambiguous.

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

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

"Use it to answer what was imported or whether an import finished" gives concrete intent-based guidance for selecting this tool. It lacks an explicit exclusion statement (e.g., "do not use this to start an import; use connections_contacts_import_contacts"), which is the only gap for a sibling set that includes two import-starting 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a small behavioral detail about multiple matches and the need to ask which one, but says nothing about return format, history inclusion, or data freshness.

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

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

Two short sentences with no wasted marketing language, and the not-found behavior is useful. The phrasing 'one of the member's people' is slightly awkward but not harmful.

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 read tool with annotations and a fully covered schema, the description is minimally adequate. However, it leaves an agent unsure how this differs from contacts_get and does not explain what 'facts and history' actually returns.

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 even though the parameter descriptions are terse placeholders ('Who.', 'History.', 'Workspace...'). The description does not clarify what 'history' toggles or how project scoping behaves, but the schema itself technically documents all three 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?

The description states the resource ('facts and history about one of the member's people') but does not use a clear retrieval verb or distinguish this from siblings like connections_contacts_get or connections_intel_remember_about_person. An agent can infer this is a read of stored intelligence, but the exact scope remains vague.

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 only guidance is a post-failure instruction ('If not found, ask which match'), which is useful for ambiguity handling but does not say when to use this tool versus contacts_get or remember_about_person. There is no explicit when-to-use or when-not-to-use condition.

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 flag destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely new policy context: health and religion facts are refused, which tells the agent to expect a rejection on those topics. It omits what 'forget' destroys exactly and whether it is reversible.

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

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

Four short sentences are front-loaded and there is no filler, but the telegraphic style ('Fact.', 'Drop.', 'Who.') borders on under-specification, and the dangling 'On which_person, ask' adds confusion rather than information.

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

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

For a 7-parameter destructive mutation with no output schema, the description covers the refusal policy but says nothing about dry_run previewing, project scoping, or what a successful save versus forget returns. It is usable but leaves real gaps.

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 each parameter already carries a description and the baseline is 3. The description adds no meaning to kind, value, forget, dry_run, or project; its only parameter-like remark references 'which_person', which is not a real parameter name.

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

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

Uses specific verbs ('Save or forget') with a specific resource ('a person fact') and explicitly bounds the domain ('Not events or payments'), which separates it from note/event/calendar siblings. The closing phrase 'On which_person, ask' is confusing because no such parameter exists in 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?

It gives clear negative guidance (not events or payments; health and religion refused), which implies when not to call it. It never names the read counterpart (connections_intel_about_person) or tells the agent to check existing facts before saving.

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 'Read-only, no side effects' merely restates structured data and earns no credit. The description does add genuine behavioral context beyond annotations: the links land the recipient already authenticated and trigger the action immediately, which explains what consuming the output does. It stops short of describing what the call actually returns (a single link, a list keyed by action, any expiry).

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

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

Two sentences, front-loaded with the core contract before the usage instruction, and the action enumeration is compressed into a single list. Slightly dense, but every clause carries information and nothing is filler.

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

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

With no output schema and only two optional, fully-documented parameters, the description does most of the remaining work: it explains what the returned URLs do and which actions they cover. The one gap is the shape of the response — whether the call returns all links at once or the agent must select one — which the agent has to infer from the action list.

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

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

Schema description coverage is 100% and both parameters (person, project) are optional and fully documented in the schema, so the baseline of 3 applies. The description mentions neither parameter and adds no information about how acting-as a person or choosing a workspace affects which links come back.

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 what the tool produces — deep-link URLs that land the member signed-in and immediately open a specific action — and enumerates the concrete actions (import Google contacts, import from a file, post a deal, browse deals, add the connector). That makes it clearly distinguishable from the action siblings like connections_import_google_contacts or connections_deal_create, which perform the actions rather than hand out links. It falls short of a 5 only because the operative verb is implied ('hand one to the member') rather than stated as 'returns deep-link URLs for X'.

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