Wavelength

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

Annotations already declare destructive=true, idempotent=false, and openWorld=true; the description adds genuinely new context — the Pro-plan prerequisite, the upsert behavior on repeat calls, and the fact that the new collaborator is returned. It doesn't explain what access is granted or how to revoke it, but it meaningfully extends 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?

Three sentences, zero padding, with purpose and the Pro-plan constraint front-loaded. Slight redundancy in restating the role default that the schema already documents keeps it from a 5.

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

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

With 3 parameters fully documented in the schema and safety traits covered by annotations, the description supplies the remaining needed pieces: plan prerequisite, repeat-call semantics, and return value (notably useful since there is no output schema). Only the lack of sibling/alternative routing keeps it below 5.

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

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

Schema description coverage is 100%, and the only semantics the description adds (default editor, role-change on re-call) are already present verbatim in the role parameter's schema description. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 (Invite/add), resource (collaborator to a Wavelength flow), and mechanism (by email with an editor/viewer role). This implicitly separates it from invite_member, add_team_member, and share_flow, but it never names those siblings to make the boundary explicit.

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

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

Gives clear context: collaboration requires the Pro plan, and re-calling with a new role changes the existing collaborator's role rather than erroring or duplicating. It offers no explicit when-not-to-use guidance or alternative tools (e.g., add_team_member for team-level access), so it stops short of a 5.

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

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

Adds substantial behavior beyond annotations: versioned snapshot creation with exact label, no AI call, rejection of edges with missing endpoints, and a detailed return contract including applied count and rejection reasons. This is unusually rich disclosure for a mutation 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 purpose, then layers enum, behavior, and return details in tight sentences. Every sentence contributes distinct information with no filler.

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

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

Given no output schema, the description compensates by describing the return shape. With annotations covering the safety profile and the description covering purpose, rejection behavior, versioning, and returns, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented structurally. The description repeats the edge-kind enum and mentions source/target rejection, but adds no new semantic meaning beyond what the schema already provides.

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

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

States a clear verb and resource: connecting nodes in a Wavelength flow. The edge kinds enumeration reinforces that this is about edges, distinguishing it implicitly from add_nodes or update_edges, but 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?

Provides no when-to-use guidance or alternatives. It does not say when to prefer add_edges over update_edges or add_nodes, leaving the agent to infer usage from the name alone.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds meaningful behavioral context beyond that: nodes are auto-placed, a versioned snapshot labeled 'Edited by AI agent (exact)' is saved, and no AI call is made. This is rich side-effect disclosure, though it does not spell out error/permission conditions.

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, purpose front-loaded, then types, formatting, placement behavior, and return shape in order of relevance. No filler.

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

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

There is no output schema, and the description compensates by enumerating the return payload (applied count, rejected list with reasons, node/edge counts, link). Combined with the 100% schema coverage, an agent has enough to call it correctly, though permission or failure conditions are not addressed.

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 flow_id and every item field. The description restates the node types and the warning/error/none status meaning, adding only the 'auto-placed' placement note beyond the schema. 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 (Add) plus resource (nodes) and scopes it to a 'Wavelength flow'. Combined with the enumerated node types and 'New nodes are auto-placed', an agent can immediately distinguish this from update_nodes, remove_nodes, and add_edges.

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?

Implies usage through behavioral cues like 'No AI call' and auto-placement, which steer it away from the AI-driven siblings (ask_flow, edit_flow). However, it never explicitly says when to reach for add_nodes versus update_nodes or remove_nodes, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: the permission model and the org-membership requirement. It does not address what happens on re-adding an existing member or whether an invitation is dispatched.

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: the operation first, then role semantics, then authorization, then the org precondition. No filler and nothing redundant with the schema.

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

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

With no output schema, return values need not be explained, and annotations cover safety. For a mutation tool the description supplies permissions and preconditions, but leaves open whether the person must already have an account or is invited, which matters given the sibling invite_member.

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 defining the semantics of each role value (team_admin manages the team, editor edits flows, viewer only opens flows) rather than just listing the enum. team_id and email are left to the schema, which is acceptable given its descriptions.

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

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

States a specific verb ('add'), a specific resource ('one person to a team') and the scoping attribute ('with a role'), which cleanly separates it from flow-level siblings like add_to_flow and add_collaborator. An agent can identify the operation 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 states the authorization prerequisites explicitly ('Only a team admin, the team owner, or an organization owner or admin can do this') and the org-team precondition. It gives clear when-you-may-use context but never names an alternative sibling (e.g. invite_member for someone not yet in the org), so there is no explicit when-not routing.

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

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

The annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=false); the description goes well beyond that by disclosing the full execution pipeline — fetch flow, AI-merge reusing existing nodes, versioned snapshot labeled 'Added notes by AI agent', and transcript append. This is exactly the additive behavioral context the 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?

It is a single dense sentence, front-loaded with the purpose and then the pipeline steps in execution order. Nearly every clause earns its place by describing a distinct side effect, though it is on the long side for one sentence.

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 multi-step, non-idempotent mutation with no output schema, the description supplies return values (new node and edge counts plus an open link) and side effects, so an agent can call it and interpret results. The one real gap is the absence of any disambiguation from the near-identical sibling 'notes_to_flow'.

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% for both parameters, so the schema already documents flow_id and text. The description only restates that text is follow-up notes merged into the flow and that flow_id must be existing, adding marginal meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('add new notes or transcript... to an existing flow') and even details the multi-step outcome (merge, snapshot, transcript append). It is clear what the tool does, but it never distinguishes itself from the very similarly named sibling 'notes_to_flow', leaving the agent unable to tell them apart from the text alone.

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

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

Usage is only implied through the phrase 'from a follow-up call', which hints at the scenario but gives no explicit when-to-use, prerequisites, or when-not-to-use conditions. It names no alternative, so the agent must guess whether this or 'notes_to_flow'/'edit_flow' is the right choice.

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

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

Annotations cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds real value beyond them: the answer is grounded only in the flow's steps/owners/systems/links, unsupported questions are answered with an explicit 'not stated' plus what is missing, and it consumes one AI help call from the plan. The quota/cost disclosure and grounding limits are meaningful behavioral context.

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

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

Three tightly scoped sentences with no filler, front-loaded with the core action before the grounding and cost details. Every sentence carries information the agent can act on.

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

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

For a two-parameter, no-output-schema tool, the description covers the action, the grounding source, failure behavior, and the AI-call cost. The main omission is how the answer is shaped/returned and how it differs from the other flow-analysis siblings.

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

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

Schema description coverage is 100%, so both parameters (flow_id, question) are already documented, including the 1000-character limit. The description adds only the implicit notion that flow_id identifies a saved flow, so the baseline 3 is appropriate.

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

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

States a specific verb ('ask a question') and resource ('one saved Wavelength flow'), making the Q&A nature clear. It is distinguishable from list/query siblings by the singular 'one saved flow' scope, though it does not explicitly contrast itself with summarize_flow or review_flow.

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 purpose implies when to use it (asking a natural-language question about a flow), but there is no explicit guidance on when to pick this over siblings like summarize_flow, review_flow, query_flows, or suggest_followups. Usage is inferable but not stated.

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

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

Annotations already declare write (readOnlyHint=false), open-world, and non-idempotent behavior. The description adds value beyond them: it explains link-selection logic (public link vs open_url) and the connection-failure error path. It does not cover duplicate/repeat-attach behavior, which is relevant given idempotentHint=false.

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

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

Three tight sentences with the primary action front-loaded, followed by link-selection and error behavior. No filler or repetition, and each sentence adds usable 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 write tool with annotations and no output schema, the description covers the destination, the link rule, and the failure mode. It omits success/return behavior and repeat-attach semantics, which is a minor gap given the annotations already flag non-idempotency.

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

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

Schema description coverage is 100%, so all three parameters (deal_id, flow_id, summary with its 1000-char limit) are already documented. The description restates the summary and link concept but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: attaches a Wavelength flow to a HubSpot deal as a note. It distinguishes itself from the many send_flow_to_* siblings by naming the concrete destination (HubSpot deal / note) rather than a generic 'send'. An agent can identify the tool 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?

Usage is implied by the CRM/HubSpot framing, and a precondition is given (HubSpot must be connected or an error is returned). However, there is no explicit when-to-use vs alternatives guidance, e.g. how this differs from the send_flow_to_salesforce/servicenow siblings or from search_crm_deals/crm_status.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds meaningful behavior: how nodes/edges are matched (by id; by source/target/kind) and exactly what the diff reports, which goes beyond the annotations.

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

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

Three tightly written sentences with zero filler; the primary purpose is front-loaded and the matching/return semantics follow logically. Every clause earns its place.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so precisely (added/removed/changed nodes with changed fields, added/removed edges with labels, one-line summary). Nothing an agent needs to invoke or interpret the result is missing.

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

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

Schema description coverage is 100%, so the schema already documents flow_id, version_a, and version_b (including the omit-to-use-current-graph semantics). The description reinforces the comparison mode but adds no syntax or format detail beyond the structured fields, so baseline 3 is correct.

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

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

States a specific verb (compare) and resource (saved versions of a Wavelength flow / the current graph), and clarifies the two comparison modes. It is easily distinguishable from siblings like list_versions and restore_version, which enumerate or revert rather than diff.

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

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

The description clearly frames the two use cases: comparing two saved versions, or comparing one version against the current graph via the optional version_b. It does not explicitly name alternative tools (e.g., list_versions to discover ids, restore_version to act on a diff), 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 it is a non-read-only, non-idempotent, non-destructive create. The description adds genuine behavioral context beyond them: edges targeting missing nodes are silently dropped, nodes are auto-laid out, and the response reports flow id, node/edge counts, and dropped-edge count. That dropped-edge disclosure is exactly the kind of side effect 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?

Front-loaded purpose, then constraints, then return values, in four tight sentences. No filler or repetition despite covering a fair amount of ground.

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

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

With no output schema, the description compensates by describing the return payload (flow id, counts, dropped edges), and the drop/auto-layout semantics round out the mutation behavior. Nothing an agent needs to call this correctly appears missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter and both enums. The description restates the node-type and edge-kind enumerations (already in the schema) and adds no per-parameter guidance, so it lands at the baseline rather than adding value.

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

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

States a specific verb and resource ('Create a saved Wavelength flow from an explicit node and edge structure') and immediately differentiates itself from the sibling create_flow_from_text via 'with no AI call.' An agent can distinguish it from the graph-building siblings without opening the schema.

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

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

'Use this when the client already has the graph' gives an explicit triggering condition that routes the agent away from the text/AI path. It stops short of naming create_flow_from_text directly as the alternative, but the 'no AI call' framing makes the boundary clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, covering the safety/mutation profile. The description adds genuine context beyond that: nodes are auto-laid out, and the return payload is enumerated (id, title, node/edge counts, labels, link). It stops short of noting that repeated calls create duplicate flows, which the non-idempotent hint implies but does not spell out.

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: purpose first, then the auto-layout behavior, then the return summary. No filler, and the most important information is front-loaded.

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

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

There is no output schema, and the description compensates by summarizing the return values an agent would see. Combined with 100% parameter coverage in the schema and entity annotations, an agent has what it needs to invoke this correctly; only the sibling routing is left implicit.

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

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

Schema description coverage is 100%, so the schema already fully documents text, title, org_id, team_id, direction, and folder_id. The description adds no parameter-level meaning beyond what the schema provides, 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 ('Turn ... into a saved Wavelength flow') and enumerates the accepted input sources (transcript, call notes, spoken description). It does not name its closest sibling create_flow_from_graph, so the agent must infer differentiation from the input type alone.

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 tells the agent what kinds of input fit (natural-language process descriptions), which implies usage, but it never says when to prefer this over create_flow_from_graph or notes_to_flow, nor any exclusions or prerequisites. Usage is implied rather than explicit.

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

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent), so the description's added value is the paid-plan prerequisite and the business rule about which flows an organization folder accepts, plus the return value. It does not cover behavior on duplicate names or on supplying both team_id and org_id, which are the remaining behavioral gaps.

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

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

Four short sentences, zero filler, front-loaded with the core action and then the routing constraints. Each sentence carries distinct information (action, prerequisite, routing, return).

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 helpfully states it returns the new folder, and it covers prerequisites and folder-type routing. Missing only edge-case behavior such as duplicate-name handling or id combination, which an agent might still need.

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 tells the agent that org_id comes from list_organizations and frames team_id/org_id as alternative routing keys rather than independent flags. It stops short of stating whether they are mutually exclusive or combinable.

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

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

Specific verb plus resource ("Create a new folder") followed by a taxonomy of the three folder kinds this tool produces, which cleanly separates it from delete_folder, rename_folder, and move_flow_to_folder. An agent can identify the operation and its scope 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?

Explicit conditional routing: pass team_id for a team folder, org_id for an organization folder, otherwise a personal folder, plus the prerequisite that personal folders require a paid plan and the constraint that only organization flows belong in an organization folder. No sibling is named as an explicit alternative, and conflicts (both ids supplied) are unaddressed, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the bar is lower. The description adds real value by disclosing the Pro gating on ai_review and the UTC time convention, but it does not warn that this creates a recurring, non-idempotent side effect (duplicate schedules) or what the call returns.

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

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

One dense but front-loaded sentence-pair: purpose first, then per-parameter semantics, then the list_loops dependency. No filler, though the kind clause is heavy and could be scanned more easily as a list.

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 creation tool with no output schema, the description omits what is returned (e.g., a loop id) and does not address duplicate/update behavior on repeat calls. The core invocation info is present, but these gaps remain.

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

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

Schema coverage is 67%, and the description compensates well: it defines each kind value, states times are UTC (reinforcing hour_utc/weekday_utc), and explains that channel is either email or a webhook:<id> sourced from list_loops. It adds genuine meaning beyond the enum lists.

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 ("Schedule a report on a Wavelength flow") and enumerates the three report kinds, so an agent knows exactly what it creates. It does not explicitly contrast with siblings like list_loops or delete_loop, hence not 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 by the kind enumeration (changes vs open_items vs ai_review) and by the note that channel must come from list_loops, which tells the agent a prerequisite call. However there is no explicit when-to-use / when-not guidance or stated alternative.

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

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

Annotations already declare non-readonly, non-destructive, non-idempotent, closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: caller becomes owner, the per-owner cap of 5 organizations, and the seat-purchase path for inviting members.

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

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

Three short sentences, front-loaded with the core action and with no filler. The billing-settings sentence is slightly tangential but still actionable, keeping it just shy of 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 a simple one-parameter create tool with annotations covering the mutation profile and no output schema, the description supplies the ownership semantics and quota limit an agent would otherwise lack. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% for the single 'name' parameter, so the schema carries the load. The description adds no syntax, constraints or format for the name, so it sits at the baseline of 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?

Specific verb+resource ('Create a new organization') with an added side-effect ('You become its owner'), so the purpose is unambiguous. It does not explicitly contrast itself with nearby siblings like create_organization_team or create_org_api_key, so it stops 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 by the resource itself, and it does describe a follow-on flow ('To invite people, the owner buys Pro seats in Wavelength Settings, Organization, Billing'). However, there is no explicit when-to-use/when-not or named alternative, so guidance remains implied rather than directive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description's added value is the authorization requirement and the membership constraint on teams, both of which are genuinely useful beyond the structured metadata. It stops short of noting failure modes such as duplicate team names or what happens on permission denial.

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 with zero filler; the core action is front-loaded and each subsequent sentence adds a distinct constraint or routing hint.

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

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

For a two-parameter mutation with no output schema, the description covers purpose, permissions, membership constraint, and the logical next step. It doesn't say whether the response returns a team id needed by add_team_member, which would be 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 description coverage is 100% and both required parameters are documented in the schema, including the note that org_id comes from list_organizations. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Create a team inside an organization'), scoping it clearly apart from siblings like create_organization and add_team_member. An agent can tell immediately which tool creates a team versus which one adds people to it.

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

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

It states the required permission ('Only an organization owner or admin can do this') and routes the agent to the follow-up tool ('Then add people with add_team_member'), plus the constraint that only org members can join. There is no explicit when-not-to-use, but the precondition and next-step routing are concrete.

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 (which only mark it non-readonly, non-destructive, non-idempotent). It discloses the critical one-time return behavior ('returned only once; Wavelength keeps only a hash'), the lifecycle caveat that the key stops working if you lose owner/admin status, available scopes, and the 10-key cap. This is exactly the behavioral context an agent needs before an irrevocable creation.

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, followed by short sentences each carrying a distinct fact (one-time return, persistence, lifecycle, scopes, quota, permissions). Slightly repetitive in re-listing the scopes already present in the enum, but otherwise efficient.

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 explaining the return, and it does so precisely (key shown only once, only a hash retained). Combined with permissions, quota, and scope details, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (label, org_id, scopes, expires_in_days) are already documented in the schema. The description restates the scope values, which duplicates the schema enum rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Make an organization API key for the Wavelength REST API') and clearly differentiates from siblings like create_organization and revoke_org_api_key. An agent can identify the operation without opening the schema.

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

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

Gives real context: 'Only an owner or an admin can do this' establishes the permission prerequisite, and 'Up to 10 active keys' signals a quota constraint. It stops short of explicitly naming alternatives (e.g. revoke_org_api_key) or stating when not to use it, so it falls just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. It does add two real facts: the check is scoped to the signed-in user, and it reports connection state plus provider. It stops short of saying what happens when nothing is connected.

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

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

Two tight sentences: the action and scope come first, the return summary second. Nothing is redundant or 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?

With no output schema, the description carries the burden of describing the return, and it does name the two returned values (connected flag and provider). It omits edge cases such as what the response looks like when no CRM is linked, which is a minor gap for a no-arg status tool.

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

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

The tool takes zero parameters, so the baseline is 4. The only scoping detail, that the result is for the 'signed-in user', is stated, but there are no parameters to document 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?

The description gives a concrete verb (Read) plus resource (connected CRM status) and even names the specific provider, HubSpot. It is easily distinguished from search_crm_deals and attach_flow_to_crm by the 'status' resource, though it never explicitly contrasts itself with those siblings.

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

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

Usage is only implied: a reader infers this is the pre-flight check to see if HubSpot is connected before invoking CRM-dependent tools. There is no explicit when-to-use statement, no when-not-to-use, and no mention of alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is largely covered. The description usefully adds the authorization precondition (must be your turn) and the id's provenance, but says nothing about what happens after a decision is recorded or that a repeat call is not idempotent.

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

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

Two tight sentences, front-loaded with the action and its precondition, then the id source. 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 could say more about the consequence of approval/changes (e.g., that the flow advances or is sent back to the requester), but for a 3-parameter decision tool the coverage is otherwise sufficient to invoke 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 goes beyond the schema by naming get_inbox and list_approvals as the sources for approval_id, which is real added meaning for how to fill the required parameter.

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 ('approve') and alternative action ('ask for changes') on the 'flow' resource in an approval context, which cleanly separates it from request_approval, list_approvals, and get_inbox among the siblings.

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

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

Gives the gating condition explicitly ('when it is the signed-in person's turn') and tells the agent where to obtain approval_id, so invocation context is clear. It does not say what to do if it is not your turn or contrast with request_approval for the requester side.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Permanently ... cannot be undone' reinforces rather than pioneers. It does add value beyond annotations by disclosing the authorization requirement ('Only the owner can delete a flow') and describing the success 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?

Four short sentences with zero filler, and the irreversible consequence is front-loaded immediately after the purpose. Because no output schema exists, the return-value sentence earns its place rather than repeating structured data.

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 the essentials for an irreversible mutation: what is destroyed, who may do it, and the return payload, with no output schema available to carry the latter. It stops short of noting cascade effects (collaborators, folder membership, active shares) that an agent might reasonably wonder about.

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

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

Schema description coverage is 100% with a single parameter whose schema text ('The id of the flow to delete') is fully self-explanatory. The description's 'by id' adds no syntax, format, or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (delete), resource (saved Wavelength flow), identifier (by id), and a distinguishing scope. Among siblings like delete_folder, delete_organization, and delete_portal, the resource named here makes the target unambiguous.

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

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

The owner-only constraint functions as a prerequisite, which is useful usage guidance. However, there is no explicit when-to-use vs. alternatives guidance (e.g. delete_folder vs. delete_flow, or restore_version for recovery); usage is implied by the resource name.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds the critical non-obvious behavior: contained flows are preserved and re-parented to unfiled, not cascaded. It also discloses the return payload {deleted: true}, which is essential since no output schema exists.

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

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

Three short sentences, zero waste. Purpose first, then the surprising behavior, then the return shape. Front-loaded and complete.

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

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

A single-param destructive tool with no output schema needs exactly this: what is destroyed (the folder), what survives (flows, re-parented), and what comes back ({deleted: true}). 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 folder_id parameter is fully documented in the schema. The description doesn't need to repeat it, and correctly doesn't. A 4 rather than a 3 because the description implies the identifier targets a specific folder whose contents survive, connecting the parameter to the safety 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?

Specific verb 'Delete' plus resource 'folder', immediately distinguishing it from create_folder, list_folders, and rename_folder.

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

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

The description clarifies the consequence (flows moved back to unfiled, not deleted), which implicitly tells an agent when this is safe to use. But it doesn't name alternatives like rename_folder or list_folders, nor does it state prerequisites.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the tool only deletes loops owned by the signed-in person, an authorization boundary an agent needs before calling it. It stops short of describing any recovery path or confirmation behavior.

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

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

Two short sentences, action first, prerequisite second. Every clause carries information and nothing is repeated from the schema or annotations.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the description supplies the ownership scope and the id source. Missing only irreversibility/permission specifics, which the annotations largely imply.

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% for the single required parameter, so the baseline is 3, but the description adds value by telling the agent where the loop_id comes from (list_loops), which the schema does not. It still gives no format hints (UUID, numeric string) beyond the schema's 'The loop id.'

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

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

States a specific verb and resource ('Delete ... loops') and adds an ownership scope ('signed-in person's'), which is more than the name conveys. It does not explicitly contrast with the other delete_* siblings (delete_flow, delete_folder, delete_organization, delete_portal), but the resource noun makes the distinction obvious.

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

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

The second sentence gives a workflow prerequisite ('Get loop_id from list_loops'), which is genuinely useful for invocation ordering. However, it offers no when-not guidance, no mention of permissions or consequences, and no alternative to consider, so usage is only implied rather than framed.

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 (destructiveHint/idempotentHint) by disclosing irreversibility, the owner-only authorization requirement, the cancelled-subscription precondition, the exact-match confirmation gate, and downstream effects on members' Pro seats and reverted flows.

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, all load-bearing; permanence and the confirmation requirement are front-loaded where an agent will read them first.

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 two-parameter mutation with no output schema, the description covers irreversibility, auth, preconditions, and side effects — everything needed to call it safely.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description only restates the exact-match requirement for confirm_name, adding little semantic detail beyond the schema.

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

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

States a specific verb and resource ('Permanently delete an organization') and immediately signals permanence, which distinguishes it from the sibling leave_organization and update_organization. An agent can identify it without opening the schema.

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

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

Gives clear when-conditions: only an owner, only after the subscription is cancelled, and confirm_name must match exactly. It does not explicitly name alternatives such as leave_organization for non-owners, leaving some routing inference to the agent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description goes further by disclosing the concrete blast radius – the public link stops working for everyone – and an important non-effect, that the flows on it are not deleted. That is exactly the kind of context annotations cannot convey.

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

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

Three short sentences with zero padding, and the core action is front-loaded ahead of the side-effect and non-effect clauses.

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

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

For a destructive single-parameter delete with an annotation set that already flags destructiveness and idempotency and with no output schema, the description carries its weight by explaining what breaks and what survives. It leaves out whether the operation is reversible/recoverable, which would be the final useful detail.

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

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

Schema coverage is 100% for the single parameter, and the schema even states the source of the id ('from list_portals'). The description adds nothing about portal_id, 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 ('Delete a client portal') on the very first sentence, and the resource 'client portal' is plainly distinct from sibling deletes like delete_flow, delete_folder, and delete_organization. It stops short of the top score because it never explicitly contrasts itself with those siblings.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternative. An agent gets no help deciding between delete_portal and save_portal or the various delete_* 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 this is a write (readOnlyHint=false) that is neither destructive nor idempotent, so the safety profile is covered. The description adds genuine value beyond that: the default title behavior, the plan-limit constraint, and the exact return contents (id, title, node/edge counts, link) despite 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?

Three tight sentences: action and scope first, then default naming and constraint, then return values. Nothing redundant or padded.

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

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

For a two-parameter mutation tool with full annotation coverage, the description is nearly complete: it covers behavior, naming default, a constraint, and return values even without an output schema. Only the explicit routing against other creation siblings is missing.

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

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

Schema description coverage is 100% and the description largely restates the title parameter's default verbatim from the schema. No additional syntax or edge-case meaning is added, 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 ('Copy a saved Wavelength flow into a new flow') plus the preserved scope ('same transcript and graph'). This clearly distinguishes it from siblings like create_flow_from_graph, create_flow_from_text, and import_* which build flows from other sources.

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 — duplicate an existing flow rather than creating or importing one — and 'Plan flow limits apply' hints at a precondition. However, it never explicitly says when to choose this over create_flow_from_graph or other creation siblings, nor states what happens when limits are hit.

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

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

Annotations declare the mutation profile (readOnly=false, idempotent=false, destructive=false), and the description adds genuinely non-obvious behavior: it saves a versioned snapshot labeled 'Edited by AI agent'. That versioning side effect is exactly the kind of trait annotations cannot express.

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

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

Three tight sentences ordered purpose, behavior, return payload. The example 'add Snowflake after Fivetran' is duplicated verbatim from the schema, which is minor waste but everything else earns its place.

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

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

With no output schema, the description usefully names the return values (new node and edge counts, plus a link). For a non-idempotent mutation it could say more about failure modes (e.g., ambiguous instructions), but the core call contract is covered.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates the schema's own example for 'instruction'. No additional format, length, or constraint guidance is added beyond what the schema provides.

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

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

States a specific verb (apply) and resource (an existing Wavelength flow) plus the modality that separates it from siblings: a 'plain-language edit instruction' rather than structured node/edge operations like add_nodes or update_nodes. The concrete example makes the operation unambiguous.

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

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

The example instruction implies how the tool is used, but there is no explicit when-to-use guidance versus the node-level siblings (add_nodes, add_edges, update_nodes, remove_nodes) or format_flow. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond them: SVG/drawio use stored node positions or fall back to auto-layout, and no flow content leaves to a third party, which is a meaningful data-handling disclosure.

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

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

Front-loaded with the core action, then one tight sentence per format, then the layout caveat and the privacy note. No sentence is redundant and nothing is 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?

There is no output schema, so the description carries the burden of describing returns and does so format by format. With annotations covering safety and the schema covering both parameters, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% (baseline 3), and the description goes beyond the bare enum by explaining what each format value actually produces, including the JSON payload contents (title, graph_nodes, graph_edges) and the auto-layout caveat. flow_id gains no extra meaning but the schema already documents it 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 (Export) and resource (a saved Wavelength flow) plus the format dimension, so an agent immediately knows this serializes a flow into another representation. It enumerates exactly what each format yields, which separates it from show_flow/format_flow in spirit, but it never explicitly contrasts itself with those siblings.

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

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

The per-format return descriptions implicitly tell the agent which format to pick for a given need (diagram string vs JSON graph vs renderable SVG vs draw.io XML), which is useful selection guidance. However, there is no explicit when-to-use/when-not guidance relative to alternatives, and no prerequisites such as permissions or flow-state requirements.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the bar is lower. The description adds genuinely new behavior: the site must be connected, and a failed connection surfaces an error pointing to Wavelength settings.

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 search action followed by chaining and failure context. Minimal waste, though the page_id sentence describes a return value rather than an input.

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 annotations covering the safety profile, the description supplies the connection prerequisite, the error path, and how results chain into send_flow_to_confluence. Enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so query and space_key are already documented. The description only restates space_key's purpose as a hand-off to send_flow_to_confluence and introduces page_id, which is not an input parameter here, so it adds little parameter-level meaning.

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

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

Specific verb+resource: 'Search the connected Confluence site for spaces and pages.' The Confluence scope cleanly separates it from sibling finders like find_jira_targets and find_notion_pages without needing to open 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 a clear downstream context: pass space_key to send_flow_to_confluence to create a page, or page_id to append to an existing page. This tells the agent what to do with results, though it never states when to prefer this finder over related 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?

The annotations already establish readOnly, idempotent, non-destructive and openWorld behavior, so the bar is low. The description adds genuinely new context beyond them: the tool depends on a connected Jira app, and the failure mode is surfaced as an error that points the user to Wavelength settings. That auth/prerequisite disclosure is the kind of thing annotations cannot express.

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

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

Four short sentences with no filler: what it searches, the project_id behavior, the downstream workflow, and the not-connected failure mode. The core purpose is front-loaded in the first sentence and everything after it is actionable.

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

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

With no output schema, the description carries the burden of saying what comes back, and it does reasonably well (projects, issues, and issue types when project_id is given) plus the downstream workflow needed to use those results. It is missing detail on result shape, pagination, or how many matches are returned, and the stray issue_key reference leaves a small ambiguity.

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

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

Schema coverage is 100% and both parameters are already documented, so the schema does the heavy lifting and a 3 is the baseline. The description largely echoes the schema for project_id (issue types) and adds no syntax or format detail; it also references an issue_key that does not appear as an input parameter, which muddies rather than clarifies the parameter set.

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 ("Search the connected Jira site for projects and issues") and the word "Jira" immediately separates it from the cluster of sibling find_* tools (find_confluence_targets, find_notion_pages, find_salesforce_records). It also names the downstream sibling send_flow_to_jira, so an agent can place it without opening any schema.

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

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

It gives clear usage context: use project_id to also enumerate issue types, and feed project_id + issue_type_id into send_flow_to_jira to create an issue, or use issue_key to comment on an existing one. That effectively defines when to call this tool (as the discovery step before writing to Jira). It stops short of any explicit exclusion or statement of when not to call 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 cover readOnly/idempotent/destructive/openWorld, so the description need only add context. It usefully discloses the scope restriction (only pages shared with Wavelength) and the unconnected-app failure behavior, both of which go beyond the annotations.

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

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

Three short sentences, front-loaded with the core purpose and free of filler. The error-handling sentence is arguably peripheral but still actionable, so it 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?

No output schema exists, so the description should ideally describe the return shape; it only hints at it via 'use a page_id,' which lets an agent infer page_ids are returned. Combined with the scope and error context, it is nearly complete for a one-param read tool.

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

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

The single 'query' parameter is 100% described in the schema ('Words in the page title. Leave empty for recent pages.'), so the description adds nothing beyond it. Baseline 3 applies when schema coverage is high and the description does not enrich parameter meaning.

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

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

States a specific verb (search) and resource (Notion pages) with a scoping qualifier ('that the user shared with Wavelength'). An agent can tell it apart from find_confluence_targets/find_jira_targets by the resource, though the description does not explicitly contrast those siblings.

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

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

'Use a page_id as the parent for send_flow_to_notion' names the downstream tool and the condition tying this search to it, which is clear context. It does not state when NOT to use it or name the competing find_*_targets siblings, so it stops short of explicit alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower, yet the description adds real value: the empty-query fallback to recently changed records, the connection prerequisite, and where the error directs the user. Return format remains unspecified.

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 purpose and scope, then fallback behavior, then the downstream linkage. Nothing is wasted.

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

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

For a two-param read tool with no output schema, this covers purpose, empty-query behavior, connection prerequisite, and follow-up action. The only gap is any description of returned fields or pagination, which is minor given a read-only search.

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

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

Schema coverage is 100% with an enum on type and a defaulted value, so the schema does the heavy lifting. The description adds the 'name' semantics of query and the type options at a high level, but nothing beyond the schema's own documentation.

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

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

States a specific verb (search/find) and resource (Salesforce opportunities or accounts) plus scope by name. Distinguishes itself from siblings like search_crm_deals and get_account, and the default-when-empty behavior is made explicit.

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

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

Gives clear context: search by name, empty query returns recently changed, and explicitly names the downstream pairing with send_flow_to_salesforce. Does not state when to use this instead of search_crm_deals or find_servicenow_records, 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 readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the sys_id output is meant for send_flow_to_servicenow, and a disconnected app surfaces an error pointing to Wavelength settings. Return shape and result-count behavior are still 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?

Three tight sentences with the purpose front-loaded and no padding; every sentence adds workflow or precondition value. The 'Use a sys_id with send_flow_to_servicenow' clause is slightly abrupt and could be clearer about what is returned.

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

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

For a simple two-parameter read tool whose annotations carry the safety profile, the description covers purpose, offline handling, and downstream sys_id usage. With no output schema, the actual result shape (list of matches, returned fields) is only obliquely implied.

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 both parameters, establishing the baseline of 3. The description's 'by number or description' mirrors the query param and the record-type enumeration mirrors the table enum, but adds no format or syntax detail beyond the schema.

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

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

States a specific verb (search/find) and resource (ServiceNow records) and enumerates the record types it covers. It clearly separates itself from find_salesforce_records, find_jira_targets, find_notion_pages, and find_confluence_targets by naming the platform.

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

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

Provides clear context: this finds ServiceNow records by number/description, and the resulting sys_id feeds send_flow_to_servicenow, which routes the agent through the correct workflow. It also flags the not-connected precondition. However, it never explicitly states when to prefer this over the sibling find_* tools or any exclusions, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing the exact mutation scope ('Only the step status changes. Labels, links, and positions stay the same.'), the reversibility mechanism ('A version is saved first, so restore_version can undo it'), and the cost ('Uses one AI build or edit from the plan'). These are the details an agent needs before a non-readOnly, non-idempotent 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?

Front-loads the action and its two modes, then uses a compact examples list and short declarative sentences about side effects. 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 still explains what changes, what is preserved, and how to reverse it, which covers the essential call-time unknowns. Minor gap: it doesn't say what the call returns (e.g., a new version id) or how to review the applied marks.

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 about the 'rule' parameter by showing three example rule phrasings, clarifying its expressive range. The 'flow_id' parameter is 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 ('Mark steps of a flow yellow (warning) or red (error) from a plain-language rule, or clear the marks'), including the clearing variant. An agent can distinguish this from edit_flow or update_nodes 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?

Concrete example rules ('flag every step that waits more than a day', 'mark steps with no owner red', 'clear all highlights') make the usage context vivid, and it points to restore_version for undo. It does not, however, explicitly say when to prefer this over edit_flow or update_nodes, so there's no exclusion 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, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior context by enumerating exactly which account data is exposed (plan, trial end date, flow counts, folder limits, mic time), which is the only place this is documented since no output schema exists.

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

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

One front-loaded sentence with no filler; the enumeration is dense but every item earns its place because there is no output schema to carry the return-field contract.

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

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

For a zero-parameter read with no output schema, the description fully discharges the return-value burden by naming each field. Minor gaps remain (no note on null/empty values, units, or free-plan behavior), but nothing required to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 by rule. The description correctly implies an implicit session-scoped target ('signed-in user') rather than requiring any identifier, matching the empty 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 clear verb ('Return') and a precisely scoped resource ('the signed-in user's current plan...'). The 'signed-in user's' framing implicitly distinguishes it from sibling org-level tools like get_organization and get_org_usage, though it never names those alternatives 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 description says what is returned but never states when to reach for this tool versus the many adjacent read tools (get_organization, get_org_usage, get_insights, get_checkin_status). No prerequisites or exclusions are given; usage must be inferred entirely from the field list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is carried. The description adds domain behavior not in structured data: Wavelength emails the owner when a flow is due, which tells the agent this read reflects an automation-driven reminder system. It stops short of describing response shape or failure modes.

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

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

Two compact sentences with the resource and scope front-loaded and no filler. The second sentence about email reminders is short and earns its place as domain context, though it could arguably be cut.

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

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

With no output schema, the description usefully enumerates the returned fields (last confirmation, interval, due date, staleness), which is exactly what an agent needs. It does not cover error cases such as an unknown flow_id, keeping it short of 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?

Single required flow_id, schema coverage 100%, so the schema already documents the parameter. The description reinforces the single-flow scope ('one flow') but adds no format, sourcing, or lookup guidance beyond that. Baseline 3 is correct.

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

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

Specific verb (Read) + resource (check-in status of one flow), and it enumerates what the status contains: last confirmation, interval in days, due date, staleness. An agent can distinguish it from the sibling update_checkin purely on read-vs-write verb.

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

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

Usage is implied by 'one flow' scoping and the read framing, but the description never states when to reach for this versus update_checkin, get_flow, or list_flows, nor any prerequisite (e.g., owner/org membership). Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description is free to add operational context — and it does: it enumerates the returned fields, discloses that the transcript is omitted by default and replaced by transcript_chars, and explains the conditional status field on nodes. This is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

The purpose is front-loaded in the first sentence and the return-shape detail follows. The middle is a dense comma-list of fields, which is information-dense but slightly run-on; it could be trimmed without loss, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so thoroughly — field list, transcript default behavior, and node status semantics. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, and both parameters are already documented in the schema with the same semantics (including the transcript default). The description largely restates rather than extends the schema, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Read one saved Wavelength flow by id.' An agent immediately knows this is a single-item read. It does not, however, differentiate itself from close siblings like show_flow, export_flow, or summarize_flow, which a 5 would require.

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 guidance on when to use this tool versus list_flows, search_flows, query_flows, show_flow, or export_flow. The only usage-adjacent content is the default behavior of include_transcript, which is invocation detail rather than tool-selection 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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds useful content context (mentions in canvas comments, approval results, loop reports) but says nothing about ordering, freshness windows, or what happens when limit is exceeded.

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

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

A single sentence, front-loaded with the verb and resource, with the colon-delimited list of inbox contents adding information without padding. There is no redundant restatement of the title or annotations.

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

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

For a zero-required-param, read-only list tool with rich annotations and a fully documented schema, the description covers what the inbox contains. It is only thin on routing versus the sibling list_approvals and on any indication of result ordering or volume.

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

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

Schema description coverage is 100% with a single optional 'limit' parameter whose type, range (1-100) and default (30) are already documented in the schema. The description adds no parameter meaning of its own, so the baseline of 3 applies when the schema does all the work.

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

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

States a specific verb ('List') and resource ('the signed-in person's Wavelength inbox') and enumerates the two content types it returns (pending approvals, recent notifications). It distinguishes itself from the generic list_* siblings by scoping to the signed-in person, but it never names the closely related list_approvals or get_checkin_status to disambiguate.

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: 'the signed-in person's ... inbox' suggests a personal-scope call, and the 'recent notifications' framing implies recency rather than exhaustive enumeration. There is no explicit when-to-use, when-not-to-use, or pointer to list_approvals for a full approval listing.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description's added value is real: a hard 200-flow scope cap, a 2+ flow minimum for AI mode, and the fact that use_ai consumes one AI insight run from the plan. That cost/quota disclosure is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loads the core behavior, then the AI mode and its constraints. Three dense sentences with no filler, though the opening enumeration of seven pattern categories is long and could be trimmed slightly.

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-shape burden and largely meets it by naming the finding categories, plus limits and quota cost. Only minor gaps remain (e.g., what 'flagged' or 'due for a check-in' concretely mean, or any pagination/limit on results).

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

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

Schema coverage is 100% and the schema already states the default false, so the baseline is 3. The description goes beyond it by explaining what use_ai actually adds (AI patterns with flows as evidence plus questions for follow-up calls) and its two preconditions, which is meaningful extra 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?

The description states a specific verb ('Find patterns') over a specific, bounded resource ('across every flow the user owns or can edit, up to 200 flows'), then enumerates the exact pattern categories returned. That cross-flow aggregation scope cleanly separates it from list_flows, search_flows, query_flows, and summarize_flow without needing the sibling 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 the condition for the optional AI mode ('Set use_ai to true to also get AI patterns') and its prerequisites ('needs two or more flows'). It does not explicitly say when to prefer get_insights over search_flows/query_flows/summarize_flow, so it stops short of naming alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond annotations: the response is authorization-dependent, since 'Only an owner or an admin sees pending invitations' — an agent must not treat missing invitations as absence of invitations. It stops short of saying what else may be hidden.

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

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

Two tight sentences with no filler: the first front-loads the scope and payload, the second delivers the one conditional behavior an agent most needs. Nothing is repeated from the schema or annotations.

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

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

With no output schema, the description correctly carries the return-value burden by enumerating the fields returned, and it flags the permission-dependent visibility of invitations. It is close to complete for a one-parameter read tool; only the alternative read tools for the same org remain unrouted.

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

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

There is a single parameter with 100% schema description coverage, including the provenance hint 'Organization id from list_organizations.' The description adds no additional parameter meaning, so the baseline of 3 applies — the schema does all the work.

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 ('Show one organization') and enumerates the fields returned (members/roles, Pro seats, seats in use, invitations, settings, flow count), which separates it from list_organizations and the narrower get_org_usage/get_org_security/get_org_audit_log siblings. It never names a sibling explicitly, so the differentiation is inferred from the field list 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?

Usage is only implied: 'Show one organization' with an org_id from list_organizations suggests a detail-view call after listing. There is no explicit when-to-use vs. get_org_usage/get_org_security/get_org_audit_log guidance and no exclusion criteria, so the agent must infer routing from field overlap.

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 read-only, idempotent and non-destructive, so the bar is lower. The description adds real value beyond those: the authorization requirement (owner/admin), the result ordering, and the pagination mechanism using before_id from the prior result. It does not mention result caps or rate limits, but the coverage is solid.

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

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

Three sentences, front-loaded with the core verb and resource, then scope, then access precondition, then pagination. The long event enumeration is dense but each item is informative; 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?

Covers purpose, authorization, ordering and paging for a 6-param read tool. Since there is no output schema, the description could have sketched the shape of a returned event (fields), which is the one remaining gap for an agent deciding whether to call it.

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

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

Schema coverage is 100% (baseline 3), but the description adds meaning the schema cannot: that before_id should come from the last result to page through, which clarifies the intended paging workflow rather than just restating the field. Minor value-add 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+resource (list organization events) with ordering (newest first) and enumerates exactly what is captured (flow views, exports, shares, member changes via SCIM, role changes, two-step verification). This scope is unambiguous and cannot be confused with siblings like get_org_usage or get_org_security.

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

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

Gives the precondition ('Only an owner or an admin can see it') and a concrete paging instruction ('Use before_id from the last result to page'). It does not name an alternative tool or state when NOT to use it (e.g., versus get_org_usage), so it stops short of full when/when-not guidance.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description still adds genuine behavioral context beyond structured fields: the auth requirement (owner/admin only) and the strong safety guarantee that secrets and API key values are never returned.

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 opening clause and the content enumeration is dense but earns its place by previewing the return shape. The two trailing sentences (no secrets, owner/admin only) are quick and high-value, though the list runs long.

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 it does so by enumerating the settings returned. It covers access requirements and the secrets caveat, leaving only minor gaps such as error behavior or output formatting.

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

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

Only one parameter exists with 100% schema description coverage, so the schema already documents org_id fully. The description adds no syntax or format detail beyond it; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Read) and resource (security settings of an organization) and enumerates the exact contents returned (2FA requirement, public links, retention, sharing limits, API keys, SCIM, audit log stream). This clearly distinguishes it from siblings like get_organization and get_org_audit_log.

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

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

The description implies usage (read security settings) and adds an access prerequisite ('Only an owner or an admin can see it'), but gives no explicit when-to-use/when-not guidance and does not name alternatives such as update_org_security or get_organization.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuinely non-structured context: an authorization constraint (owner/admin only) and the window over which usage is aggregated, both of which affect whether a call will succeed.

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

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

Two tight sentences. The returned metrics are front-loaded, followed by the time window and the permission gate, with no filler or repetition of the title.

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

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

There is no output schema, so the description must carry the return-shape burden, and it does by enumerating the six metric categories returned per member. Combined with annotations covering safety and the schema covering parameters, an agent has everything needed to select and call this tool.

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

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

Schema coverage is 100%, with both params documented, including the enum-like days values and the org_id source (list_organizations). The description restates the 7/30/90 window but adds no format, default, or error semantics beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource (get organization usage) and enumerates exactly what is returned: seats used, active members, AI calls, mic minutes, flows, and two-step verification status. This clearly separates it from siblings like get_org_audit_log, get_org_security, and get_insights without needing to open any schema.

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

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

Gives the supported time windows (last 7, 30, or 90 days) and a hard prerequisite: only an owner or admin can see it. It does not explicitly name an alternative tool or say when not to use it, but the context and permission gate are clear enough to invoke correctly.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds value by enumerating the returned fields (is_public, url, summary, views, published_at, hide_attribution), which compensates for the absent 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?

Two sentences, front-loaded with the purpose and then the return fields. There is no filler or repetition.

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

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

For a simple status getter, the description covers purpose and return fields, while annotations cover safety and the schema covers the sole parameter. It could mention error conditions or the unshared case, but it is largely 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% for the single flow_id parameter, so the schema fully documents its meaning. The description adds no additional parameter semantics, making the baseline 3 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 ('Read'), resource ('public sharing status for a Wavelength flow'), and the returned fields. It is clearly distinct from siblings like share_flow and unshare_flow.

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?

No explicit when-to-use or when-not-to-use guidance is given. The purpose implies the tool is for checking share status, but it does not name alternatives or prerequisites.

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

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

Annotations already carry the safety profile (readOnly, non-destructive, not open-world), yet the description adds real value beyond them: non-persistence ('Nothing is saved'), a cost/plan disclosure ('Uses one AI help call from the plan'), and partitioning semantics ('Every note goes in exactly one group'). The AI-call cost note is exactly the kind of trait annotations cannot express.

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

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

Three short, front-loaded sentences; the core behavior leads and the constraints follow. The workshop example is repeated verbatim from the notes parameter description, which is minor waste, but nothing is padded.

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

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

There is no output schema, so the description should carry return-format information. It hints at the shape ('each group gets a short title') but never states concretely what comes back (a list of groups with their assigned notes), leaving the response structure partly implied for a tool whose whole purpose is restructuring input.

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

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

Schema description coverage is 100%, so both parameters (notes, title) are fully documented in the schema itself, including item length and count bounds. The description adds only a redundant example and nothing about format or constraints 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?

Specific verb (group) and resource (notes) with the organizing dimension (by theme) stated explicitly, plus a concrete example ('sticky notes from a workshop'). It reads as a distinct operation, but it does not name or contrast itself with the nearest sibling (notes_to_flow), so an agent gets no explicit routing cue.

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 workshop-sticky-notes example implies the intended context, so use is inferable. However, there is no statement of when to prefer this over alternatives such as notes_to_flow or notes_to_flow pipelines, and no exclusions or prerequisites.

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

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

Annotations already declare this as a non-readonly, non-idempotent, non-destructive, open-world mutation. The description adds substantial extra context: that it makes no AI call, reads the dbt Discovery API applied state or a job manifest, defines the exact node/step/system/edge mapping rules, states the 250-node limit, and explains default environment selection.

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 core action and remains dense with useful detail across a few well-organized sentences. Every sentence earns its place given the nine parameters and complex mapping behavior; there is no filler or repetition.

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

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

For a complex, nine-parameter write tool with no output schema, the description is complete enough: it explains creation behavior, list_only output, selection defaults, environment fallback, node limits, and what the resulting flow contains. Safety-relevant traits are already covered by annotations.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful interaction semantics beyond the schema: select maps upstream lineage, downstream true extends to downstream dependencies, omitting select maps the whole project under a node cap, omitting both environment_id and job_id picks the first deployment environment, and list_only changes output from a flow to a list.

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 states a specific verb and resource: mapping dbt lineage into a new Wavelength flow, with the distinctive note 'no AI call.' It then details exactly what becomes data nodes, steps, systems, and edges, distinguishing it from generic flow-creation or other lineage imports.

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 clearly explains how to use key parameters: select for upstream lineage, downstream to extend it, no select for whole-project (if ≤250 nodes), and no environment_id/job_id for the first deployment environment. However, it never names sibling alternatives like import_snowflake_lineage or create_flow_from_graph to tell the agent when to select this tool over them.

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

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

Annotations cover only the mutation profile (readOnlyHint=false, non-destructive, non-idempotent). The description goes well beyond them, disclosing data loss (positions and colors are not kept, the flow is re-laid out), multi-flow splitting behavior ('one flow per workflow, up to 25'), node limit ('up to 250 nodes'), and the return payload. This is exceptionally rich behavioral context.

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

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

Front-loads the core purpose, then the accepted formats, then the transformation rules, then the return value. It's dense but every sentence earns its place – the format enumeration and the 'up to X' limits are all decision-relevant. It could be slightly terser on the format list.

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

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

Given no output schema, the description correctly closes the loop by stating what is returned (flow id(s), detected format, node/edge counts, open links). Combined with the transformation semantics and limits, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds the default title behavior ('first node label') and the auto-detection of format, but doesn't expand on team_id, folder_id, or direction beyond the schema. 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+resource ('Turn an existing diagram or automation into editable Wavelength flows') and enumerates exactly which source types are supported. It clearly distinguishes itself from siblings like import_from_n8n, import_dbt_lineage, and create_flow_from_text by being the general-purpose multi-format importer.

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

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

Provides clear context: 'with no AI call' and 'Pass the source as text', which tells the agent this is a deterministic parser rather than an AI-powered creation path. It doesn't explicitly state when to prefer this over import_from_n8n or import_dbt_lineage, but the breadth of accepted formats implies its role.

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

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

Annotations declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real context beyond them: draw.io/Mermaid/SVG bypass AI, import_only returns text with no flow, and only files Wavelength created or the user picked can be opened. The disconnected-Drive error behavior is also disclosed. 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 core purpose is front-loaded in the first clause, and each subsequent sentence carries distinct information (file types, import_only mode, access restriction, error handling). The file-type list is a bit dense but earns its place by defining supported inputs.

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 covers supported inputs, the import_only return mode, access constraints, and error behavior for an 8-parameter (all optional) tool. It could say more about the returned flow/text shape, but for this tool the coverage is solid.

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 eight parameters; baseline is 3. The description reinforces import_only semantics ('get the text back without making a flow') but adds no syntax, format, or default details beyond what the schema fields already state.

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

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

States a specific verb (read) and resource (Google Drive file) and the resulting action (make a flow), then anchors it to a named sibling with 'the same way as create_flow_from_text'. It also enumerates the file types it consumes, so an agent can distinguish it from text- and diagram-based siblings without opening the schema.

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

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

Gives clear context: use it to import from the connected Drive, with 'import_only' as an alternative mode that returns text instead of creating a flow, and notes the Drive-connection prerequisite and its error behavior. It lacks explicit when-not guidance versus other import siblings (e.g. import_diagram, import_from_n8n), so it falls short of a full 5.

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

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

Annotations already cover the mutation/idempotency/open-world profile, and the description adds real value beyond them: creation of NEW flows (non-destructive), no AI call, a 25-workflow limit, and a precise account of how source nodes map to target node types. It does not address failure behavior or required n8n connection state, keeping 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?

Purpose is front-loaded, followed by a dense but informative mapping sentence, then the limit and the id-source hint. The mapping enumeration is long yet earns its place by telling the agent what the import will produce.

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

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

For a 4-param, fully-documented tool with no output schema, the description covers purpose, transformation semantics, limits, and the ID prerequisite. It is complete enough to invoke confidently; only failure/rollback and connection prerequisites are 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 coverage is 100%, so all four parameters are already documented, including the 'up to 25' limit and the list_n8n_workflows provenance. The description restates rather than extends that, so the baseline 3 applies.

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

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

States a specific verb (map/import) and resource (n8n workflows into new Wavelength flows), and immediately distinguishes itself from AI-based creation with 'with no AI call'. The detailed node-mapping sentence makes the transformation concrete, setting it apart from siblings like import_dbt_lineage or import_from_google_drive.

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

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

Provides an explicit prerequisite ('Get ids from list_n8n_workflows') and a hard cap ('Up to 25 workflows per call'). It does not spell out when NOT to use this tool or name the AI-alternative sibling (e.g. create_flow_from_text), so guidance is clear but not fully exclusive.

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 this is a non-read-only, non-idempotent, open-world operation, and the description adds the details that matter on top of that: read-only source queries, the Enterprise edition prerequisite, the 250-node cap when schema is passed, and the creation of a *new* flow each time (consistent with idempotentHint=false). It also summarizes the return payload, which is important given 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?

Four dense but zero-waste sentences: purpose first, then data sources, then the node/edge mapping model, then scoping and return value. Every clause carries operational 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?

For a tool with seven parameters, no output schema, and a non-trivial ingestion pipeline, the description covers prerequisites, source behavior, mapping rules, scoping limits, and return contents. An agent has enough to invoke it correctly without opening additional resources.

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 beyond the schema: the schema parameter keeps only that schema 'and its direct neighbors (limit 250 nodes)' and the days window is described as applying to writes and loads. The remaining parameters (title, team_id, folder_id, direction) get no extra narrative, which is acceptable since the schema 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 resource: map Snowflake data lineage into a new Wavelength flow, with the notable qualifier 'no AI call'. This clearly separates it from sibling import_dbt_lineage and from create_flow_from_text, which do different things.

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 strong context for when the tool applies and what makes it succeed: it reads ACCOUNT_USAGE object dependencies, access history writes, and stage/Snowpipe loads, and it requires Enterprise edition for access history. It does not, however, explicitly route the agent between this and import_dbt_lineage or state 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 flag openWorldHint, non-idempotent, and non-destructive, and the description adds substantial context beyond them: the invitation is address-bound, expires in 7 days, consumes a Pro seat per member and per pending invite, and surfaces a specific seat-exhaustion error with the resolution path. That is exactly the behavioral detail an agent needs before invoking an outbound-email 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?

Four short sentences, each carrying distinct information: scope, invitation mechanics, seat cost, and failure handling. The core action is front-loaded and there is no filler.

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

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

With no output schema, the description still covers the relevant outcome behavior by describing the expiry window and the seat-exhaustion error. Combined with a fully covered input schema and rich annotations, 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 org_id, email, and the role enum with its default are already fully documented in the schema. The description's 'as member or admin' only mirrors the enum values and adds no syntax, format, or sourcing detail beyond what the schema provides, 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 ('Invite one person to an organization by email') and pins the scope to a single invitation, distinguishing it from siblings like add_collaborator, add_team_member, or create_organization. The role option ('as member or admin') further sharpens what the call does.

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

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

Gives clear operational context: role selection, seat consumption per member/pending invite, and the error path plus remedy ('the owner adds seats in Billing'). It does not explicitly name when to prefer this over add_collaborator or add_team_member, so it stops short of full alternative 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 declare destructiveHint=true and idempotentHint=true, but the description adds substantive context they cannot express: what happens to organization flows (reassigned to transfer_to or the first other owner) and the ownership precondition that blocks the call. It does not discuss confirmation, auth requirements, or what happens to non-flow resources, so it is strong but not exhaustive.

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

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

Three dense sentences with the purpose front-loaded first, then the transfer consequence, then the blocking precondition. Every sentence carries information; only the opening 'Leave an organization' partially restates the title.

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

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

For a destructive two-parameter mutation with no output schema, the description covers consequences, ordering of the transfer fallback, and the hard precondition that would otherwise cause a failure. Missing only secondary details such as irreversibility or whether other resources (collaborators, API keys) are affected.

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 transfer_to's fallback behavior ('or to the first other owner') — a semantic detail the schema does not provide. org_id is left to the schema, which already points at list_organizations.

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 (leave) and resource (organization) in the first sentence, and the rest of the description makes clear how this differs from delete_organization or remove_member by describing the flow-transfer handoff. It never names the sibling tools explicitly, so differentiation is implicit rather than spelled out.

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

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

Gives a concrete precondition ('The only owner cannot leave; make another member an owner first') and an alternative path ('or delete the organization'), which is real when-to-use and when-not-to-use guidance. It stops short of naming delete_organization by tool name, so an agent must map the phrase to the sibling itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral detail beyond that: results are ordered newest first, approvers appear in order, and the response additionally includes the pool of people who can open the flow and therefore act as approvers — a non-obvious return characteristic.

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 action and ordering, then the extra return content. Efficient, though the second sentence's phrasing ('and so can be approvers') is slightly roundabout.

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 it does so (ordering, approver sequence, status, candidate approvers). It omits pagination/result limits and whether only pending approvals or all historical approvals are returned.

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

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

Only one parameter (flow_id) and schema description coverage is 100%, so the schema fully documents it. The description confirms the approvals belong to a Wavelength flow but adds no syntax, format, or sourcing guidance for the id. Baseline 3 applies.

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

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

States a specific verb and resource ('List the approvals on a Wavelength flow') and adds real scope detail: newest-first ordering, per-approver ordering, and status. It doesn't explicitly distinguish itself from related siblings like decide_approval, request_approval, or get_flow, so it stops 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?

The description never says when to reach for this tool versus decide_approval, request_approval, or get_flow, nor does it state any prerequisite (e.g. that the caller must be able to view the flow). Usage is only inferable from the verb.

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/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new context by disclosing the returned fields (channel_id, label, kind, last delivery status) in the absence of an output schema, plus the per-user scoping. It omits ordering/pagination behavior, keeping it out of 5 territory.

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

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

Two sentences, zero waste: the enumeration of supported kinds and the return payload come first, and the handoff instruction (use channel_id with send_flow_to_channel) closes it.

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 input parameters and no output schema, the description carries the return-shape burden itself and does so by naming the four fields, so an agent has everything needed to call it and consume 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States a specific verb and resource (list chat channels and webhooks) and enumerates the supported platform kinds, so an agent can distinguish it from list_connections, list_teams, and other list_* siblings at a glance.

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 downstream use case: retrieve channel_id then call send_flow_to_channel. It does not state when not to use it or contrast with an alternative list tool (e.g. list_connections), so it falls just short of explicit 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it enumerates the return contents (owner, is-signed-in-user-owner flag, each collaborator's email and role) and explicitly states the share token is never returned, which is a meaningful disclosure for a sharing-related 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?

Two sentences, both front-loaded with the essential information (what is listed, what is returned), and zero filler. The security-relevant exclusion is placed last, after the positive return 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, the description correctly carries the burden of describing return values and does so concretely, including the role enum values and the share-token exclusion. It is only slightly short of complete in not mentioning call prerequisites or behavior for a flow with no collaborators or an invalid flow_id.

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

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

There is a single required parameter (flow_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or sourcing guidance for the id, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (collaborators on a Wavelength flow), which cleanly separates it from the add_collaborator, remove_collaborator, and remove_external_collaborators siblings. An agent can pick this tool 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?

Usage is implied by the name and resource: call it when you need to see who currently has access to a flow. There is no explicit statement of when to use this versus alternatives (e.g., get_share_status, get_flow) and no prerequisites such as required permissions or ownership.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: exactly what is surfaced (account, sending tool per integration, channel/webhook counts) and the constraint that connecting requires a browser sign-in in Wavelength settings. It omits return formatting details, but no output schema exists to lean on.

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 what is listed before the auxiliary sign-in note. Every clause carries information, though the trailing sentence about browser sign-in is slightly tangential for a read-only listing 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?

For a zero-parameter, read-only listing tool with no output schema, the description is nearly self-sufficient: it enumerates the integrations and the per-entry fields an agent should expect. It could be fuller on whether counts are scoped per-user or per-workspace, but nothing required for a correct invocation is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate, and the schema is empty as expected. Baseline 4 applies; no parameter-level claims are made or needed.

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

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

Names a specific verb+resource ('Show which outside apps the user has connected') and enumerates the concrete contents returned: connected account, per-app sending tool, chat channel and webhook counts. An agent can distinguish this from siblings like crm_status or list_channels 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?

Usage is only implied. The description says connecting an app needs a browser sign-in and that this tool tells the user where to connect it, which hints at a discovery/status use case, but it never states when to use this versus list_channels, crm_status, or the find_* target tools, and gives no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is covered. The description adds valuable context beyond them: the connection prerequisite, the specific fields returned per environment, and the recommended downstream handoff.

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 listed, followed by the prerequisite and the follow-up routing to import_dbt_lineage. Three sentences, each carrying information, though the connection-setup detail could be trimmed slightly.

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

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

With no output schema, the description compensates by summarizing the returned environment fields and mentioning jobs. Combined with the prerequisite and downstream usage, it is nearly complete for a no-arg list tool.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface that the description needs to explain.

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: listing the connected dbt account's environments (with id, name, type, project) and jobs. The name/title emphasize 'jobs' while the description foregrounds environments and jobs equally, but an agent can still tell this apart from siblings like list_snowflake_databases. It names import_dbt_lineage as the downstream consumer, aiding differentiation.

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

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

Gives a real prerequisite (the user must connect dbt under Settings > Connected apps > dbt Cloud) and states what to do with the output (pass a deployment environment_id or job_id to import_dbt_lineage). It doesn't explicitly say when NOT to call this tool, so it falls just short of 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description goes further by disclosing ordering (newest first), the meaning of 'shared' (true when the user is not the owner), and the role vocabulary, which are behavioral traits not present in structured fields.

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

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

Two sentences, front-loaded with the core behavior and scope, then the refinements and return shape. The return-field enumeration is somewhat long 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?

With no output schema, the description usefully enumerates the returned fields and explains the 'shared' and 'role' semantics. Gaps remain around pagination beyond the limit cap (no offset/total count) and no explicit routing to sibling search tools.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including case-insensitivity and the 1-100 range. The description restates the same filters without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (List), resource (saved Wavelength flows), scope (signed-in user's), and ordering (newest first). It implicitly separates itself from search_flows/query_flows by emphasizing 'saved' and 'signed-in user's', but never names an alternative 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?

It presents the optional filters (query, folder_id, limit) as available refinements, which implies usage, but gives no explicit guidance on when to use this versus search_flows, query_flows, or list_folders/list_versions. No exclusions or selection conditions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the exact per-folder fields returned and the fact that plan-level folder limits, personal folder count, and create-folder capability flags are also included. No output schema exists, so this disclosure carries real weight.

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, no filler, with the action and scope front-loaded before the return-value details. Every clause earns its place by describing either the operation or its output.

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 input parameters and no output schema, the description supplies the return shape (id, name, team_id, flow_count) plus plan limits and capability flags, which is close to what an agent needs. It does not state pagination or sorting behavior, 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?

Zero parameters, so there is no argument semantics to explain; the baseline for a no-param tool is 4. Nothing in the description misrepresents the empty input schema.

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

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

States a specific verb (List) and resource (folders) plus scope (the signed-in user's folders). The scope clause distinguishes it from sibling list tools such as list_flows, list_organizations, and list_teams, which target other resources.

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 scope (signed-in user's folders) implies when to reach for it, but there is no explicit when-to-use statement, no prerequisites, and no routing to alternatives like list_flows or create_folder. Adequate but leaves inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds domain context about what is listed (loop categories and postable chat channels), but says nothing about response shape, pagination, or ordering.

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

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

A single front-loaded sentence with the verb and resource first and no filler. The trailing parenthetical is dense but informative; the sentence is appropriately sized for a simple list tool.

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

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

For a one-parameter read-only list tool with full schema coverage and annotations carrying the safety profile, the description is largely sufficient and even names the content it returns. Without an output schema, a bit more detail on the returned structure would help, keeping it from a 5.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents flow_id fully. The description does not add any format, source, or constraint details for flow_id, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (scheduled loops) scoped to 'a Wavelength flow', with parenthetical examples of loop types (changes digest, open items, AI review) and a note that chat channels for posting are also returned. It does not explicitly differentiate itself from siblings like list_channels or create_loop/delete_loop, so it falls 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 only implied: the agent can infer this is for inspecting loops on a given flow. There is no explicit when-to-use statement, no mention of alternatives such as list_channels or get_flow, and no stated prerequisites beyond the required flow_id.

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, idempotentHint, non-destructive, openWorld), so the bar is lower. The description usefully adds the connection prerequisite and the shape of the response fields (id, name, active, node count, tags, last update), which is real context beyond the annotations.

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

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

Three tight sentences: what is listed, what is returned, the prerequisite, then the downstream use. Front-loaded with the action and scope and with no filler.

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

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

There is no output schema, and the description compensates by naming the returned fields, plus the setup prerequisite. It is close to complete for a no-arg list tool, though it does not say what happens when n8n is not connected or when no workflows exist.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate; the field list it gives is about output, not inputs.

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

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

States a specific verb (List) plus resource (workflows) scoped precisely to "the user's connected n8n instance", which distinguishes it from the many generic list_* siblings like list_flows. It also enumerates the returned fields, so an agent knows exactly what it gets.

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 the ids with import_from_n8n" gives a clear downstream use and implicitly frames the tool as the discovery step before import. The connection prerequisite (Settings > Connected apps) is stated. No explicit exclusions or alternative routing, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it enumerates the fields returned (role, member count, Pro seat count), which matters because there is no output schema. It doesn't cover pagination or empty-result behavior.

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

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

Two sentences, zero filler: the first defines the operation and its return payload, the second gives the follow-up action. Front-loaded with the core 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?

For a zero-param, read-only list tool with no output schema, the description covers what is returned and how to use it, which is most of what an agent needs. Minor gaps remain around ordering/pagination and the empty case, but nothing blocking.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description's mention of org_id is about consuming output elsewhere, not about an input here, so no further parameter detail is needed.

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

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

Specific verb (List) plus resource (organizations) with an explicit scope qualifier ('the user belongs to') and the exact payload returned: role, member count, Pro seat count. This clearly distinguishes it from the singular sibling get_organization and from list_teams/list_channels.

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 tells the agent what to do with the output ('Use org_id with create_flow_from_text or move_flow_to_organization'), which is genuine routing guidance. It does not, however, state when this tool is preferable to get_organization or when it should be skipped, so it stops short of full when/when-not coverage.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond that: it explains portals are public client-facing pages where viewers comment/vote without an account, and it discloses the exact return shape (ids, name, url, flow ids, settings, plan limit), which is essential given 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?

Two tight sentences, front-loaded with the action and resource before the definitional context. Every clause earns its place, since the portal definition and return shape are the only way an agent learns this domain concept without an 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?

With no parameters, no output schema, and rich annotations, the description supplies exactly what is missing: what a portal is and what the call returns. An agent has everything needed to invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing about parameter syntax is needed, and the description correctly adds no misleading 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?

States a specific verb (List) and resource (client portals of the user), then defines what a portal actually is. An agent can instantly distinguish this read-only listing from siblings like save_portal, delete_portal, and get_share_status.

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

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

The description implies usage by scoping to the user's own portals and providing domain context, but never states when to use this versus sibling read/portal tools (e.g., get_flow or get_share_status). No explicit alternatives or exclusions, so the guidance stays at the 'implied' tier.

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