sociahive

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

With no annotations, the description carries the behavioral burden; it discloses that activation makes the flow process triggers in production and that keyword conflicts with other published flows surface as advisory warnings to relay. It does not cover edge cases like idempotency, permissions, or behavior when the flow is already active, but the core state change and warning surface are stated.

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 terse, front-loaded sentences: main behavior, invocation examples, and lookup guidance. No filler and no repetition of schema fields.

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

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

Given a low-complexity tool with only two params and no output schema, the description covers what it does, how to identify the target, and what to relay to the user. It omits only secondary operational details such as return values and handling of an already-active flow, which are not required for correct selection and invocation.

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

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

The schema has 0% coverage and both params are optional, so the description must add meaning; it does so by telling the agent to identify the flow by flowName and explicitly saying no id lookup is needed. This effectively documents flowName as sufficient and flowId as unnecessary, though it does not describe formats or when flowId might still be preferred.

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

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

The description uses an explicit verb and resource: 'Publish (activate) a flow so it processes triggers in production', and anchors it with natural-language examples ('turn on the welcome DM'). It is clearly distinct from siblings like deactivate_flow and publish, so selecting it doesn't require opening schemas.

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

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

It gives clear context for when to invoke: when a flow should go live in production, and supplies example utterances. It also includes one exclusion, 'its name is enough, no id lookup,' but does not explicitly contrast with alternatives such as deactivate_flow or update_flow, so it falls short of a full when/when-not guide.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose an important limitation upfront ('Rejects mutations against published flows') and explains that edges define execution flow. But it omits other behavioral details such as persistence, side effects, validation behavior, or what happens when sourceHandle is missing.

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 no filler. The core operation is first, the most important optional parameter semantics follow, and the usage triggers are front-loaded with a necessary restriction at the end. Every sentence earns its place.

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

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

For a mutation tool with 7 parameters, no annotations, and no output schema, this description gives the essential purpose, a useful sourceHandle example, and a key restriction. It is functional but not fully complete: optional parameters are unexplained, return behavior is absent, and there is no mention of how to reverse or replace edges.

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

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

Schema description coverage is 0%, so the description must compensate. It does add real meaning for sourceHandle with the concrete 'button-0' example and implies source/target semantics via 'connect two nodes'. However, data, type, targetHandle, and flowId are left undocumented, leaving significant parameter meaning to inference.

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: 'Connect two nodes in a flow with an edge.' It also clarifies what an edge is ('defines the flow execution path'), and the natural-language examples make the intended operation unmistakable. This clearly separates it from siblings like add_node, update_flow, and delete_edge.

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

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

Provides explicit trigger phrasing: 'Use when the user says "connect the welcome message to the discount step" / "wire button 1 to the next node".' This is clear context for when the tool applies. However, it never states when not to use it or mentions alternatives such as update_flow or update_node for other connection-related changes.

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

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

With no annotations, the description must disclose behavior on its own. It does reveal that mutations are rejected against published flows and implies a mutation nature. However, it does not state what happens on success, whether the node is immediately saved, if any validation occurs per type, or the return value. This is a notable gap 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?

The description is reasonably concise and front-loaded: it states the core purpose first, then lists node types, then gives usage context and a restriction. The type list is long but necessary; no redundant filler is present.

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

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

The tool is complex: it accepts 5 parameters, includes a nested position object, and has many type-specific data requirements. The description does not explain how to construct data for each node type, what position means beyond x/y, or the omitted enum values. Without an output schema, the description leaves too much unspecified for correct invocation.

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

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

The description substantially explains the type enum by mapping values to human-readable meanings (delay→wait, condition→branch, etc.). However, it omits three accepted enum values (message, trigger, custom) and provides no explanation for flowId, position, data, or name beyond the raw schema. With 0% schema coverage, this only partially compensates.

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

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

The description opens with 'Add a node to a flow's graph,' which precisely names the verb and resource. The enumerated node types further clarify the tool's scope, and the purpose is clearly distinct from sibling tools like add_edge, delete_node, and update_node.

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

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

It explicitly frames the tool for 'conversational flow building' with an illustrative example, and provides a when-not condition: 'Rejects mutations against published flows — duplicate first.' However, it does not name alternative tools for other operations (e.g., add_edge), so it lacks explicit sibling differentiation.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that items fill failed Autopilot slots later and always go through review. Crucially, it states that adding never publishes anything, which prevents misconceptions about immediate posting. This goes beyond a simple 'add' description and provides 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 sentences deliver purpose, usage triggers, and a key behavioral caveat without any fluff. The action is front-loaded in the first sentence, so an agent immediately knows what the tool does. Every sentence adds distinct value.

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

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

The description covers purpose, usage, and critical behavior, which is good for a relatively simple two-parameter tool. However, it omits any explanation of the sourcePostId parameter and does not describe return behavior, which might matter given no output schema. The missing parameter context keeps it from being fully complete.

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

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

The schema has zero description coverage, so the description must compensate. It only hints at the text parameter via 'caption text' and gives no information about sourcePostId. An agent calling this tool would not know what sourcePostId refers to or how it relates to the destination. This is a significant gap given the lack of schema-level 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?

The description clearly states the action: 'Add a recyclable post (caption text) to the user's evergreen queue.' The verb-add plus the evergreen-queue resource makes it distinct from sibling tools like schedule_post or publish. It also clarifies scope with the phrase 'never publishes anything.'

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

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

The description provides explicit usage triggers: 'Use for "save this as evergreen" / "recycle this post".' It implies when not to use it (when immediate publishing is intended) by stating that adding never publishes. It doesn't name alternative tools explicitly, but the context is sufficient for an agent to select this tool over publication-focused 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?

With no annotations, the description carries the full burden. It discloses the key behavioral effect: 'Expires the current draft and regenerates a fresh week', which implies a destructive action. It also mentions graceful handling of edge cases (no week, still generating, already approved), which helps set expectations. It does not mention permissions or reversibility, but the core side effect is disclosed.

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

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

The description is concise and well-structured. It front-loads the purpose with 'Use when...', then gives the call guidance, the effect, and edge cases in just a few sentences. No filler or redundant information; every sentence adds value.

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

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

The description covers when to use the tool, what it does, and edge cases, which is good for a moderate-complexity tool. However, it fails to explain the batchId parameter, which is essential for correct invocation. The absence of an output schema is partially mitigated by the edge-case statement, but the missing parameter documentation makes it incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains 'feedback' via examples ('make it more casual', 'fewer promos') and mentions it is optional (omit for regeneration), but it does not explain 'batchId' at all. The agent cannot infer what batchId refers to from the description, leaving a significant gap in parameter understanding.

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

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

The description clearly states the tool's purpose: to change/adjust/revise the current autopilot week with feedback or regenerate it from scratch. It specifies the resource (current week) and the action (expires and regenerates), and differentiates itself from the sibling generate_autopilot_week by focusing on the existing week rather than creating a new one.

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

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

Explicitly tells the agent when to use this tool: when the user asks to change or revise the current week with feedback, or to regenerate it without feedback. It also instructs to call directly without reading status first, providing clear guidance on the invocation flow and distinguishing this tool from status-checking 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?

With no annotations provided, the description carries the full burden and it delivers: it warns that the action is irreversible, requires typed confirmation, schedules posts to the real audience, returns cleanly when no week is ready, and reports unscheduleable posts per-post rather than dropping them. This is strong behavioral 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?

The description is dense but every sentence earns its place: trigger, invocation guidance, irreversible consequence, and edge-case return behavior. The most important usage rule 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?

Given there is no output schema and no annotations, the description covers all essential operational facts: invocation variants, side effects, confirmation requirement, and return behavior for empty or partially unscheduleable weeks. An agent has enough to call this tool correctly and warn the user appropriately.

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

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

Schema coverage is 0%, so the description must compensate. It explains batchId well: omit it for the current week, or provide a YYYY-MM-DD week start. It implies the confirm parameter's role through 'REQUIRING typed confirmation' but never explicitly says 'confirm must be true', leaving a small inference gap.

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

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

The description names a specific verb-resource pair: approve/ship/publish the week. It is not a tautology and clearly distinguishes this from siblings like generate_autopilot_week and adjust_autopilot_week by framing the action as an approval/go-live rather than generation or adjustment.

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

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

It explicitly states when to call ('Use when the user asks to approve/ship/publish the week'), how to invoke it ('Call directly'), and what not to do ('never read status first to find an id'). It does not name sibling alternatives by tool name, but the exclusion of the status-reading approach is clear and practical.

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

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

With no annotations provided, the description carries the full behavioral burden. It reveals soft-delete semantics, scheduler-side scope (published posts stay LIVE on the platform), the requirement for a typed confirmation that prevents unconfirmed deletion, and per-post failures in the results array. These are meaningful behavioral disclosures beyond the schema.

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

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

The description is dense yet front-loaded: the core function appears first, followed by the first-call pattern, anti-patterns, and behavioral caveats. Every sentence carries operational value with 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 tool with two nested parameters, no output schema, and no annotations, the description provides a complete operational picture: invocation method, side effects, scope, and result reporting. It covers everything an agent needs to call it correctly and avoid common mistakes.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the filter parameter as a set descriptor that the server expands, and postIds as an alternative to be used only when IDs are already held. This adds essential semantic meaning to the bare schema types.

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

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

The description states the exact action: 'Soft-delete up to 50 scheduler-side posts in ONE call.' It clearly distinguishes from the sibling delete_scheduled_post by explicit contrast and calls out the plural nature of the operation. The verb and resource are specific and unambiguous.

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

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

The description provides an explicit invocation protocol: use filter on the first call to let the server expand the set, pass postIds only when already known, never fan out delete_scheduled_post, and never list first. It also gives a concrete use case ('remove all expired draft posts'), leaving no doubt about when to use this tool.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It handles this well by disclosing the 50-post limit, non-blocking per-post failures, failure categories, and the ISO 8601 format for scheduledAt. It does not mention whether the operation is reversible or what authorization is required, but core behavior is clearly disclosed.

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

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

Three sentences carry the essential information with no filler. The action, scope, usage trigger, failure behavior, and date format are all front-loaded and each sentence earns its place.

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

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

Given no output schema and no annotations, the description does a solid job by mentioning the results array for per-post failures and the 50-post cap. It omits how timezone interacts with scheduledAt and does not describe the overall response shape in detail, but an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful meaning by specifying that scheduledAt must be ISO 8601, but it says nothing about the optional timezone parameter or how postIds are interpreted beyond their schema type. Partial compensation only.

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

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

The description names a specific operation—moving scheduled posts to a new publish time—and sets a concrete scope: up to 50 in one call. The example 'push all Friday's posts to Monday' clearly distinguishes this from single-post scheduling or deletion tools in the sibling list. This is unambiguous and actionable.

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

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

The description explicitly says 'Use when the user says...' and gives a realistic bulk-rescheduling request, which gives clear context for when this tool is appropriate. It does not name alternatives or state when not to use it versus individual update tools, so it falls short of full 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?

With no annotations, the description carries the behavioral burden and does disclose key traits: the 50-flow cap, that only name/description are patched (not graph or status), and that partial failures do not abort the rest. However, it does not clarify what happens if a filter matches more than 50 flows, whether `filter` is required, or how `filter` and `flowIds` interact when both are supplied.

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 text is dense and front-loaded: the key message, batch limit, and use case appear in the first sentence, and each subsequent sentence earns its place with a distinct behavioral or usage constraint. The high-contrast formatting (caps and code ticks) aids quick parsing.

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

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

Given there is no output schema and no annotations, the description covers the essential operational model, parameter roles, and partial-failure behavior. It is slightly incomplete on edge cases like an oversized filter expansion, response shape, and the exact validity of a `patch`-only call, which an agent would need for fully reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that `filter` {status, nameContains} describes the set for server-side expansion, `flowIds` is only for when IDs are already known, and `patch` covers identity fields only. It does not elaborate on valid status values or whether `filter` and `flowIds` are mutually exclusive, so it is strong but not exhaustive.

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

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

The description opens with a specific, scoped action: 'Batch-edit up to 50 flows in ONE call', then narrows the resource to 'every PLURAL flow edit' and explicitly limits patches to identity fields (name, description). This clearly differentiates it from single-flow tools like update_flow and from structural tools like add_edge or delete_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 description gives direct when-to-use guidance: use it for plural flow edits, describe the set with `filter` first, pass `flowIds` only when already held, and 'never fan out per-flow tools, never list first'. This explicitly routes the agent away from per-flow alternatives and states the intended calling pattern.

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

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

With no annotations available, the description fully carries behavioral disclosure: it identifies the tool as internal, explains the cacheControl breakpoint semantics, and states that calling it is a no-op returning an empty object. No behavioral surprises are left undocumented.

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

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

The description is short and front-loads the critical warning 'LLM should never invoke.' Each sentence adds either a usage constraint, a reason for existence, or the no-op behavior, with no wasted wording.

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

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

For a parameterless internal marker with no output schema, the description is fully sufficient: an agent knows not to call it, knows what it is for, and knows what would happen if it did. Nothing required for correct handling is missing.

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

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

The schema has zero parameters, so there is little to document. The description adds the relevant meaning that this is a marker with no arguments and no operational effect, matching the baseline for a parameterless tool.

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

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

The description states it is an internal cache-point marker whose invocation is a no-op, and explicitly says the LLM should never invoke it. This is a clear, specific purpose that sets it apart from all sibling tools.

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

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

It explicitly instructs the agent to never invoke the tool and explains its placement-based role at the end of the tools array. For an agent, the correct usage is clear: do not select it.

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

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

With no annotations available, the description carries the burden of behavioral disclosure. It clearly states the state transition (scheduled → draft), the consequence (won't publish), and idempotency behavior for already-draft posts. It omits edge-case behavior like not-found handling, but the core behavior is transparent.

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

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

The description is front-loaded with the main effect, then gives practical examples and idempotency details without fluff. Every sentence adds value, and the structure leads with the most important 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 simple tool with two optional parameters and no output schema, the description covers the action, result, identifier strategy, and idempotency. It does not specify behavior when both postId and postName are provided, but that is a minor gap for such a straightforward operation.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains postName as the caption/opening words and clarifies when to use it as an identifier instead of postId. postId is left self-explanatory from its name, which is acceptable given the fallback guidance.

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

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

States a specific verb and resource: cancel a scheduled post, with the precise effect of reverting it to draft so it won't publish. This clearly distinguishes the tool from siblings like delete_scheduled_post and update_scheduled_post, which have different outcomes.

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

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

Gives concrete usage signals: user phrasings like 'cancel that scheduled post' and 'don't publish Tuesday's post', plus a fallback identification strategy using postName when no id is available. It doesn't explicitly say when to prefer delete_scheduled_post or update_scheduled_post, but the intended use-case is well implied.

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

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

With no annotations present, the description carries the behavioral burden. It discloses two non-obvious traits: the find-or-create pattern (mutation may or may not occur) and idempotency with no double-counting. It does not mention side effects of the lead-outcome beyond recording it, but the key behavioral risk is adequately covered.

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 deliver the core behavior, the identity key, and the crucial idempotency trait with zero waste. The opening phrase 'Capture a lead' immediately anchors the tool's 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 5-parameter tool with no annotations and no output schema, the description is missing essential context: what 'source' means despite being required, whether username/displayName affect behavior, and what the return value communicates. An agent could call it correctly only by inferring these details.

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

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

Schema coverage is 0%, so the description must compensate. It explains that platform and platformUserId form the identity for find-or-create. However, the required 'source' parameter is only an enum with no meaning explained, and the optional username/displayName are not addressed at all, leaving an agent unsure what values to supply.

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 resource (a lead/contact), the key identity tuple (platform, platformUserId), and the action (find-or-create and record a lead-outcome). This fully distinguishes it from the sibling tools, which are about flows, scheduling, publishing, and analytics rather than lead capture.

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

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

The description gives clear context for when to use the tool: any time a lead needs to be captured from a platform user identity. It does not list exclusions or alternatives, but no sibling tool competes for the same job, so an agent can confidently select it without further 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?

Without annotations the description must carry the transparency burden. It does disclose the most important behavior: the tool returns a draft and preview and does not go live. It does not state whether the draft is persisted, what account scoping effect accountId has, or any auth/rate-limit considerations, leaving some behavioral uncertainty.

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, and the critical safety boundary is at the end but still prominent. The description front-loads the action and input, then states the output and non-live guarantee efficiently.

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

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

The core draft-and-preview contract is clear enough for a simple call, and the required input is explained. It is not fully complete because there is no output schema, the optional accountId is unexplained, and the description does not point the agent toward the sibling tools that would turn the draft into a live automation.

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

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

With 0% schema description coverage, the phrase 'natural-language outcome' adds meaning to the required outcome parameter. But accountId is never discussed in the description or schema, and there is no guidance on how the outcome string is interpreted into automation details, so compensation for the missing parameter docs is only partial.

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

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

The description uses a specific action ('Draft an automation') and names the input mode ('natural-language outcome'), and 'returns a DRAFT + preview; never goes live' gives a clear identity separate from live-activation siblings. It still does not explicitly relate it to closely named tools like generate_flow or generate_multiple_flows, 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?

'Never goes live' provides a usable boundary: this is the drafting/preview tool, not an activation tool. However, the description never says when to prefer create_automation over create_flow/generate_flow or how to make the returned draft live, so the routing is implied, not 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states the broadcast is a draft, never sends, lands ready for human review, and that consent and tier quotas are enforced in the composer. This meaningfully clarifies side effects and limits of the operation.

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

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

The description is compact and front-loaded: it opens with the direct-call instruction and the draft-safety guarantee. The examples and audience/channel explanations each add necessary value, and no sentence is wasted.

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

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

For a tool with nested parameters and no output schema, the description covers purpose, usage, channel, audience, and send behavior well. The only notable gap is not explaining the default/omitted audience behavior or what the created draft returns, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful semantics for channel (listing all six values), audience types (all, segment, tags), and match behavior (any/all). It leaves name and message to be inferred from context, but those are relatively self-evident.

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

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

The description clearly identifies the verb and resource: 'Create a one-time broadcast as a DRAFT'. It also distinguishes the tool from generic content-creation siblings by specifying broadcast/announcement asks and explicitly noting it never sends. This is specific enough for an agent to tell it apart from similar create_* tools.

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

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

The description gives explicit when-to-use triggers with concrete user phrasings like 'broadcast the drop to my VIP tags on WhatsApp' and 'send a message to all my subscribers'. It also says to call directly without whoami or context lookup. It does not name an alternative tool, but the context is clear enough for most selection decisions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It says the flow is a draft, has no nodes/edges yet, and that trigger configuration is optional with a fallback to user selection in the canvas. This is meaningful behavioral context beyond the schema, though it does not describe response shape or side effects in detail.

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

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

Three sentences, no filler, and the core action is front-loaded. Every sentence adds distinct value: what it creates, when to use it, how to proceed, and the alternative path. This is an appropriately sized, well-structured 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?

The description covers the creation intent, empty draft state, trigger fallback, and next steps via add_node/add_edge. However, since there is no output schema, it does not explain what the tool returns or how the agent should obtain the flow ID needed to reference the created flow in subsequent calls. That is a meaningful gap for invoking the tool correctly in a multi-step workflow.

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

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

Schema description coverage is 0%, so the description is expected to compensate. It adds key semantics for the trigger parameter by stating it is optional and what happens if omitted. However, it does not explain accountId, platformUserId, platform, or description beyond what their names imply; the schema structure and enums do most of 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?

The description opens with a specific verb and resource: 'Create a new empty automation flow as a draft.' It clearly distinguishes this from siblings like general flow creation and from generate_flow, which builds flows from descriptions. An agent can immediately tell what this tool is for.

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

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

It explicitly states when to use it ('Use when the user wants to start from scratch') and names the alternative: 'call generate_flow instead to have AI build it from a description.' It also points to add_node and add_edge for the next steps, giving clear routing and sequencing 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?

With no annotations, the description carries the burden. It does disclose a critical behavior: the widget is created as a disabled draft, not live until manually enabled by a human. This is valuable. However, it doesn't disclose potential side effects like whether creating a draft counts against limits, if any content is validated, or what happens on failure. It adds some context but not comprehensive.

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

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

The description is concise, two sentences, and front-loaded with the core purpose and the key behavioral constraint (disabled draft). It uses clear, direct language without unnecessary filler. Slightly more could be added about parameters, but it is efficient for its length.

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

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

Given the tool's moderate complexity (5 params, 3 required), the description covers the main purpose and the critical draft behavior. However, it lacks guidance on required parameters (name, widget_type, headline) and how they relate to the widget's purpose. Without an output schema, it also doesn't explain return values. Enough for a basic call but with clarity gaps.

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

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

Schema description coverage is 0%, so the description must compensate. The description mentions 'widget_type' implicitly by listing types, but does not explain other parameters like 'name', 'headline', 'body', or 'button_text'. The schema provides structure but no semantics. The description adds some context about widget types but leaves other parameters' purpose unclear.

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

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

The description clearly states the tool creates a website growth widget and lists specific widget types (popup, slide-in, bar, embed box). It distinguishes it from siblings by focusing on widget creation rather than flows or landing pages, though it doesn't explicitly name a sibling to differentiate from.

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 its use case (signup popups, announcement bars, embedded capture boxes) which helps an agent understand when to use it. However, it doesn't explicitly state when not to use it or mention alternatives like create_landing_page or create_flow. The guidance is implied but not fully explicit.

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

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

With no annotations, the description carries the full behavioral burden and it delivers key facts: the page is created disabled, requires a human to enable it, is served at /p/<slug>, and tier limits apply at that point. It stops short of describing the immediate return value or whether creation can be undone, so 4 rather than 5.

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

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

Four sentences, front-loaded with the core action and draft state, then the trigger, required inputs, and post-enable behavior. Every sentence adds relevant information and there is no filler.

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

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

For a 5-parameter creation tool with no output schema and no annotations, the description covers the key context: input expectations, slug default, lifecycle from draft to human enablement, URL, and limit behavior. A small gap is the lack of any statement about what the call returns, which the empty output schema does not fill.

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

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

Schema description coverage is 0%, so the description must compensate. It covers the slug generation default and lists headline, body, and button_text, but it does not add much semantic meaning beyond the property names, and it does not mention constraints like maxLength or the slug pattern. This is adequate but leaves gaps.

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

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

The description names the specific operation: 'Create a hosted lead-capture landing page' and immediately disambiguates it by stating it is created as a DRAFT and is not publicly live until a human enables it. It also gives a concrete trigger phrase, making the tool's purpose unmistakable and distinguishing it from sibling creation tools like create_growth_widget.

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

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

It provides an explicit when-to-use trigger: 'Use when the user says...'. It does not list exclusions or alternatives, but the draft/disabled behavior gives the agent enough context to recognize when this is the right tool.

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

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

No annotations provided, so the description carries the burden. It discloses that the link is 'inert until shared; deletable' and counts clicks per link. However, it doesn't mention any auth requirements, idempotency, or what the response looks like. Adds some behavioral context but not comprehensive.

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

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

The description is moderately sized but information-dense. It front-loads the core purpose, then adds example queries, usage guidance, and behavioral notes. Each sentence adds value, though the flow could be slightly tighter.

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

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

For a 3-param tool with no output schema, the description covers purpose, usage, and some behavior, but omits the 'platform' parameter and doesn't describe the return value or error cases. It also doesn't mention if the link is immediately usable after creation. Incomplete but adequate for the most common call.

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

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

Schema coverage is 0%, so the description must compensate. It explains that 'name' is the only required field and that flow_id 'deep-links into that automation.' However, the 'platform' parameter is left entirely unexplained, and there is no detail on formats or constraints beyond the schema. Partial compensation.

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 clear verb and resource: 'Create a shareable tracked ref link' with specific functionality (per-link click counting, primitive behind referral links). It includes concrete example queries, making the purpose unmistakable. It doesn't explicitly differentiate from siblings, but the scope is specific enough that confusion is unlikely.

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

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

Explicitly states this is a FIRST call tool requiring only a name, and names what NOT to do first (whoami, current_page_context, list_accounts). It also clarifies the optional flow_id's role. This gives clear when-to-use and 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?

No annotations are provided, so the description carries the disclosure burden. It explains account resolution behavior ('the server resolves the connected account'), the natural-language or ISO format for scheduledAt, and that omitting scheduledAt produces a draft. It does not describe the response, but the creation/scheduling behavior is clear.

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

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

Every sentence earns its place: use-case examples, the critical 'NEVER call list_accounts first' warning, parameter syntax, and routing to siblings. The primary action is front-loaded, with richer guidance following in a structured way.

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

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

For a 5-param tool with no annotations and no output schema, this covers selection, scheduling semantics, account resolution, and sibling routing. The only omissions are media/timezone semantics and return behavior, but neither blocks correct invocation.

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

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

Schema description coverage is 0%, and the description compensates for the most non-obvious parameters: platforms should only contain the platform name, and scheduledAt accepts natural language or ISO. text is inferred from 'supplied content', though media and timezone receive no semantic guidance 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?

The opening line uses a specific verb+resource ('Create a NEW social post') and explicitly scopes to posts that do not exist yet ('Use whenever the post does not exist yet'). It also distinguishes itself from schedule_post and publish_post_now, and the examples clarify the intended use.

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?

Directly states when to use ('Use whenever the post does not exist yet') and gives concrete user-intent examples. It explicitly excludes existing drafts ('For an EXISTING draft use schedule_post'), warns against list_accounts, and routes immediate publishing through publish_post_now.

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

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

With no annotations, the description carries the full burden and does it well. It discloses that the sequence is created as a draft, that a human must later activate and enroll contacts, that consent and tier quotas apply at that later stage, and that email steps are sent only to opted-in contacts. This is strong behavioral disclosure for a creation tool with no structured annotations.

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

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

The description is compact and front-loaded with the most important fact (DRAFT). The step definitions are concise, use consistent structure, and every clause adds either behavioral context or parameter meaning. No filler or redundancy beyond the useful repeated emphasis on draft.

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 the tool's complexity, the description covers purpose, usage triggers, parameter shapes, side-effect behavior, and post-creation workflow. The main gap is the missing explicit mention of the required 'name' parameter and the lack of any return-value information, since there is no output schema to provide that context.

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

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

Schema description coverage is 0%, but the description compensates by explicitly naming the three step types and their key fields: message (text, optional platform, delay_minutes), delay (delay_minutes), and email (subject, body, opted-in note). However, it omits the required top-level 'name' parameter entirely and does not mention the optional 'description' parameter, so compensation is incomplete.

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

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

The description opens with a specific verb and resource: 'Create a drip sequence as a DRAFT.' The DRAFT qualifier clearly distinguishes this from sibling creation tools like create_flow or activate_flow, and the phrasing tells an agent exactly what object is produced.

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

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

The description gives explicit user-intent triggers ('make a 3-day welcome sequence', 'build a nurture cadence', 'email drip for my newsletter leads'), so an agent knows when this tool is appropriate. It doesn't name alternatives or give when-not-to-use guidance, but the examples and the draft vs. activate distinction provide clear usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently reveals two non-obvious behaviors: the consent prerequisite and idempotency on name collision (returning created=false). It does not detail the success response structure, but for a simple create operation these disclosures are substantial and beyond what the schema alone conveys.

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 waste. The purpose is front-loaded, followed by the two key constraints (consent and idempotency). Every word earns its place, and the structure is optimal for agent scanning.

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

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

For a simple tool with two parameters and no output schema, the description covers the essentials: purpose, consent requirement, and idempotency behavior. It does not explicitly state the success return value (e.g., created=true) or any side effects, but these are reasonably inferred. The description is sufficient for an agent to invoke the tool correctly without missing critical constraints.

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 50% (only 'name' has a description; 'color' does not). The tool description adds no additional parameter information—it does not explain color format, default values, or interactions between parameters. Since coverage is not low (<50%) and the description does not compensate, a baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Create a tag') and is clearly distinct from sibling search_tags. The idempotency note further clarifies the tool's purpose as a creation operation with collision handling, leaving no ambiguity about what it 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?

Explicitly states a critical usage condition: 'ONLY after explicit consent.' This is a clear 'when to use' guideline. However, it does not mention alternatives (e.g., search_tags to check for existing tags) or provide 'when-not' scenarios beyond the consent requirement, 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?

With no annotations present, the description carries the burden of behavioral disclosure. It communicates that the tool is a read/inspection operation with no side effects, and it adds useful context that the result duplicates the existing <page_context> block and that calling it unnecessarily wastes a turn. It does not explicitly mention permissions or error behavior, though those are less critical for a zero-parameter context reader.

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

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

The description is compact and front-loaded: the return content comes first, followed by precise usage conditions and a caution against wasted calls. Every sentence earns its place, with no filler or restating of the tool name.

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

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

For a zero-parameter, no-output-schema tool, the description is complete: it defines what is returned, when to use it, when not to use it, and why. An agent has everything needed to invoke it correctly and avoid unnecessary calls.

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

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

The tool has zero parameters and the schema coverage is trivially complete. Per the rubric, zero-parameter tools receive a baseline of 4, and the description appropriately focuses on the output rather than parameters.

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

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

The description names a specific verb ('Returns') and a concrete resource: what the user is looking at, including route, entity type/id/name, and selection. This clearly distinguishes it from the many action-oriented sibling tools, and the 'Use ONLY when' clause reinforces its unique role.

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

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

The description explicitly states when to call it — when the user asks what page they are on or when the <page_context> block reads '(none …)' — and when not to call it: when <page_context> already names an entity. This is direct, actionable routing guidance that leaves little to inference.

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

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

With no annotations, the description carries the behavioral burden. It discloses idempotence ('already-draft flows return success unchanged') and the side effect (flow stops processing triggers). It does not mention authentication, permissions, or whether the action affects other resources, but for the stated operation it gives sufficient transparency.

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

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

The description is compact and front-loaded: purpose in the first phrase, usage examples next, and the practical pointer about flowName and idempotence after. Every sentence adds distinct value and there is no filler or repetition of schema fields.

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

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

For a simple two-parameter tool with no output schema and no heavy annotations, the description covers intent, identification, and behavior. The main gap is that it does not explicitly state whether at least one of flowId/flowName must be supplied, given the schema marks zero parameters as required. Still, the core information an agent needs to correctly call it is present.

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

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

Schema description coverage is 0%, so the description must compensate. It explains flowName well ('its name is enough, no id lookup') and implies that flowId is an alternative identifier that is not required. However, flowId is never described in terms of format or when to use it, leaving half of the parameter surface unexplained.

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

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

The description opens with a specific verb and resource ('Unpublish (deactivate) a flow') and clearly states the effect ('stops processing triggers'). It distinguishes the tool from siblings like activate_flow and delete_flow by using 'unpublish' and 'deactivate' and by including natural-language phrasings, so an agent can confidently pick it over related tools.

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

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

The description provides concrete user-intent examples ('pause this flow', 'stop the welcome DM', 'unpublish') and tells the agent to identify the flow by flowName without a lookup. It implies when to use this tool, but does not explicitly state when not to use it or contrast it with delete_flow or activate_flow, so it stops short of the fullest 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?

With no annotations provided, the description carries the behavioral disclosure. It clarifies the destructive scope ('only the wiring between them is removed', 'nodes themselves stay') and a guard condition ('Rejects mutations against published flows'). It doesn't mention reversibility or permissions, but the most important behaviors are disclosed.

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

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

The description is three sentences with no filler. It front-loads the action, then adds scoping, usage examples, and a constraint. Every sentence earns its place.

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

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

For a simple two-parameter deletion tool, the description covers what is removed, what is preserved, when to use it, and a critical failure condition. It doesn't describe the return value or reversibility, but those are not essential for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds conceptual meaning by explaining that an edge is a connection between nodes and that the operation happens within a flow, which maps to edgeId and flowId. However, it doesn't explain how to discover or format these IDs, leaving some ambiguity for the agent.

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

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

The description states a specific action ('Remove a single edge'), names the object ('edge/connection'), and explicitly distinguishes itself from node deletion by saying 'nodes themselves stay'. This makes the tool's purpose immediately clear and differentiates it from siblings like delete_node.

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

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

The description provides explicit usage triggers with natural-language examples ('disconnect the welcome from the discount') and a key constraint ('Rejects mutations against published flows'). It doesn't name sibling alternatives explicitly, but the usage context is strong enough to guide an 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses that the operation is non-destructive, requires typed user confirmation, is reversible for at least 30 days, and rejects flows in the publishing state. This is far beyond a typical delete description.

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

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

The description is dense but every sentence earns its place: core behavior, trigger phrases, identification strategy, safety guarantee, reversibility, and a state-based rejection condition. It is front-loaded with the most important information and contains no filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential selection and invocation context very well. The only gaps are the vague '<page_context> entity' reference and lack of detail about what happens on success or when the flow is not found.

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

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

Schema coverage is 0%, so the description must compensate. It meaningfully clarifies that flowName is sufficient and explicitly instructs the agent not to look up the id first. However, it does not explain the role of flowId or how the page_context entity maps to the schema, leaving minor ambiguity.

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

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

The description opens with a specific verb and resource: 'Soft-archive a flow (status='archived')'. It clearly distinguishes this from destructive deletes by explicitly stating 'The call destroys nothing', and natural-language examples like 'delete this flow' help an agent recognize the intent.

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

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

It gives explicit invocation guidance: identify by flowName or page_context entity, never look up the id first, and use update_flow status='draft' to reverse the archive. It also states a rejection condition ('Rejects flows in 'publishing' state'), which is directly actionable.

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

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

No annotations exist, so the description carries the burden. It discloses important destructive behavior: cascading removal of all referenced edges and clean re-rendering. It also states that mutations against published flows are rejected. It doesn't mention permissions, reversibility, or error/return behavior, but it covers the most critical operational traits.

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

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

Three sentences, each earning its place: the main action, the critical cascade behavior, and the routing/usage guidance. The warning about delete_flow is repeated slightly but remains compact and 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?

Given the tool's low complexity (two scalar params, no nested objects, no output schema), the description covers the key context: scope, cascade behavior, restriction on published flows, and sibling differentiation. It could add where nodeId comes from or how failures surface, but it is adequate for correct selection and invocation.

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

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

Schema description coverage is 0%, and the description provides no direct explanation of flowId or nodeId, their formats, or how to obtain them. The phrase 'from a flow' and 'single node' only indirectly imply their roles. The parameter names are somewhat self-explanatory, but the description adds almost no semantic detail beyond what the schema already shows.

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

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

The description states a specific action ('Remove a single node from a flow') with a clear verb and resource. It also explicitly differentiates from delete_flow, so an agent can distinguish it from a similarly named sibling without opening the schema.

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

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

It gives direct trigger examples ('remove the email collection step' / 'delete the followup message'), explicitly contrasts with delete_flow, and warns that published flows reject mutations. This gives an agent both when-to-use and when-not-to-use 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?

With no annotations, the description fully carries the behavioral burden and does so thoroughly: soft-delete internals, cancellation of BullMQ jobs and queue rows, non-recoverability via dashboard UI, no effect on already-published platform media, user confirmation required, and rejection of publishing-state posts. No important side effect is left undisclosed.

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 main purpose is front-loaded and every paragraph adds a meaningful constraint or side effect. A few ideas are restated (scheduler-side/not platform-published, and the live-post behavior is repeated twice), so it is slightly more verbose than necessary, but still efficient for a destructive operation with many edge cases.

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

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

Given no annotations and no output schema, the description covers the critical operational context: irreversibility, what gets cancelled, what stays live, confirmation, and state restrictions. The only notable gap is how the post should be identified via postId/postName, which leaves a small ambiguity for invocation.

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

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

The schema has 0% description coverage and the description never mentions postId or postName. It does not clarify whether the two identifiers are alternatives, whether both are expected, or how the tool resolves posts by name. The parameter names are self-explanatory, but the description adds no semantic value beyond them.

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

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

The description opens with a specific verb and resource ('Delete a scheduler-side post') and immediately clarifies scope with 'hidden from all dashboards, won't publish' and 'not platform-published.' This makes the tool's function unambiguous and distinguishes it from publishing/deletion tools for live content.

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

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

It gives clear when-not guidance: already-published posts stay live on the platform, and the agent does not delete published media. It also states constraints ('Requires user confirmation', 'Rejects posts in publishing state'). It does not explicitly name alternative tools such as cancel_scheduled_post or bulk_delete_scheduled_posts, so it stops short of a full when-to-use vs alternatives statement.

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

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

With no annotations, the description carries the behavioral burden and does so well: it clarifies that the post itself is untouched and that an already-live automation continues running, i.e. this detaches rather than deletes. It omits edge cases such as behavior when no automation is attached or permission requirements.

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 clauses: the action first, the effect on post/automation second, the parameter guidance third, and the negative constraint last. The quoted example costs little and improves matching; no sentence 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?

For a two-parameter, no-annotation, no-output-schema tool, the description covers purpose, side effects, and parameter selection adequately. Only the no-op/error case when no automation exists is left unstated.

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

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

Schema coverage is 0%, so the description must compensate, and it does: 'Identify the post by `postName` when you have no id' explains the relationship and fallback order between the two otherwise undocumented parameters. It does not describe id format or whether supplying both is legal, leaving a small gap.

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 ('Remove the comment automation from a scheduled post') and immediately distinguishes itself from enable/activate siblings with 'Never turns anything on.' An agent can identify this as the detach-only 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?

Provides the natural-language trigger phrase ('remove the automation from Tuesday's post') and a negative usage rule that steers away from activation tools. It stops short of naming an explicit alternative (e.g. delete vs. detach tooling), so it is contextual rather than fully routing.

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

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

With no annotations provided, the description carries the full burden and handles it well. It discloses that OAuth tokens are cleared, the status flips to disconnected, a typed user confirmation is required, the action is not reversible via the agent, the user must redo OAuth, and all flow automation on the account stops. This is unusually transparent about side effects.

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

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

Every sentence earns its place. The description starts with the core action and effect, gives real user utterances, then delivers call-level instructions, confirmation behavior, and irreversible consequences. It is dense but not bloated, well ordered, and free of 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?

The description is very complete for a disconnected mutation tool: it covers invocation, parameter selection, confirmation, reversibility, and downstream effects. It lacks an explanation of what the accountId parameter is for and does not describe the response or error behavior, but since no output schema exists and the operational context is richly covered, the definition is strong with only a minor residual 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?

The schema has three parameters with zero description coverage, so the description must compensate. It gives clear meaning to platform ('the platform they named IS the target') and handle ('narrows it when several are connected'). However, accountId is not explained at all, leaving one of three parameters undocumented. Overall, it adds strong semantic value beyond the bare schema, with a minor gap.

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

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

The description clearly states the tool's function: 'Disconnect a connected social account — clears OAuth tokens, flips status to

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

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

The description provides explicit when-to-use guidance via example user intents, instructs that the platform named by the user should be passed directly on the first call, and explicitly warns against calling list_accounts first. It also explains when to use the handle parameter and notes that a typed user confirmation is required, which is essential operational 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?

With no annotations, the description carries the full burden. It discloses that the copy starts in draft and that editing/publishing are separate steps, which is useful. However, it does not explain what exactly is copied (nodes, edges, settings), whether the original is modified, or any side effects or permission requirements. This is a moderate 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?

The description is compact, front-loading the core purpose, then providing parameter guidance and outcome expectation in three clear sentences. Every sentence adds value with no redundancy.

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

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

Given no annotations, no output schema, and incomplete parameter documentation, the description leaves important gaps: it does not clarify the role of flowId, what constitutes a 'copy' (scope of duplication), or any constraints (e.g., uniqueness of newName). An agent could call this tool incorrectly without this information.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It covers flowName and newName, but completely omits flowId. The description suggests flowName is the identifier, but does not clarify how flowId relates or when to use it. This is a significant gap for an agent.

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 clear action ('Copy an existing flow as a new draft') with specific examples ('duplicate flow X', 'clone the giveaway flow'). It distinguishes from siblings like create_flow and update_flow by making clear this is a copy operation, not a fresh creation.

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

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

The description explains how to identify the source (by flowName) and how to name the copy (newName). It also notes that the copy starts as a draft, implying the user must publish separately, which gives context for when this tool is appropriate versus alternatives. However, it does not explicitly mention when NOT to use it or name alternatives like create_flow.

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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It implies a read-only dependency lookup, but it never states that it has no side effects, what it returns, or how results are limited or paginated. This is insufficient for a tool with no annotations.

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

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

The description is two short sentences with no filler. The core scope is front-loaded and the deletion caveat is expressed economically. Every sentence earns its place.

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

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

The description gives the tool's scope and a clear usage trigger, which is useful for a simple lookup. However, there is no output schema and no statement about response shape, whether it returns flow objects or counts, or error behavior, leaving some ambiguity for the agent.

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

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

Schema description coverage is 0%, so the description needs to compensate. 'Flows referencing a tag' meaningfully connects entityType and entityId to the query, and the schema's enum pins entityType to 'tag'. However, the limit parameter and the exact semantics of entityId (e.g., ID vs. name) are left to the schema.

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

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

The phrase 'Flows referencing a tag' clearly identifies the tool's output—flows that reference a tag—and the tool name 'find_references' supplies the verb. It is distinct from sibling tools like list_flows and search_tags, though it is terse and could be more explicit about the returning behavior.

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

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

'Use before tag deletes' gives an explicit trigger condition for when to call this tool: before a destructive tag deletion, to discover dependent flows. It does not name alternative tools or exclusions, but it provides practical usage context beyond the schema.

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

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

With no annotations, the description fully discloses behavior: it enqueues a ~90s build and returns the artifact immediately, it is idempotent per week, and it produces drafts that are not published until approved. This is comprehensive and adds value beyond the name and schema.

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

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

The description is concise, about four sentences, each adding essential information: trigger condition, direct call instruction, async behavior, idempotency and alternative, and draft status. It is front-loaded with the usage trigger and avoids redundancy.

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

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

The description covers the key behavioral aspects (async, idempotent, drafts) but omits any explanation of the 'feedback' parameter and does not describe the structure or format of the returned week artifact. Given there is no output schema, the agent may not know how to interpret the artifact. It also doesn't mention any prerequisites like whether autopilot needs to be enabled, though the instruction to call directly mitigates that. Overall, mostly adequate but with clear gaps.

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

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

The schema has one parameter 'feedback' with no description, and schema description coverage is 0%. The description does not mention or explain the 'feedback' parameter at all, so the agent has no guidance on what to pass. The name suggests providing feedback, but that is not explicit. The description fails to compensate for the missing schema description.

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

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

The description states a specific verb+resource: generate this week's content, and differentiates from siblings by clarifying it returns a draft and that adjust is for changes. It also says to call directly without reading status, distinguishing it from status-related tools. This is clear and specific.

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

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

Explicitly states when to use it (user asks to generate/create/make/plan the week) and when not to (use adjust to change an existing week). It also advises calling directly without reading status first, giving clear procedural guidance. It implicitly contrasts with approval and status tools.

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

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

No annotations exist, so the description carries the full burden and does so: server-side async generation with a 10-30s latency expectation, the artifact-card completion signal, stale-ID warnings ("Never trust your previous turn's tool result for node IDs"), and the full error contract with recovery.kind branches. It even discloses that iterateOnFlowId is refused once a person has edited the flow — a non-obvious mutation constraint.

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

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

Purpose is front-loaded in the first sentence and the body is organized under clear behavioral headings, so it is scannable despite its length. Some space is spent on conversational-tone policy (how to phrase the chat opener) that is arguably agent demeanor rather than tool contract, which makes the block bulkier than strictly required.

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

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

No output schema exists, yet the description still explains what the caller observes after invocation (the card flipping to "Built · <flow name> →" with node count) and how failures surface, which is the right division of labor. With five parameters including a nested object and one enum, the uncovered `platform` parameter is the only material 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 0%, so the description must compensate, and it largely does: `description`, `businessContext` (with all six nested fields enumerated: industry, product, keyword, offer, tone, dataFields), `variants`, and `iterateOnFlowId` semantics are all explained beyond the bare schema. The `platform` enum parameter (instagram/whatsapp/messenger/telegram) is never mentioned in the description, leaving one of five parameters undocumented anywhere.

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 an explicit input modality: "Generate a complete automation flow from a natural-language description." It also routes the agent away from itself where appropriate, naming update_node / add_node / delete_node for single-edit cases, so the agent can distinguish it from sibling mutation tools without opening a schema.

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

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

Explicit when-to-ask-first rule ("Ask one short question BEFORE calling only when the request is too vague to determine trigger or outcome AND you have zero context"), explicit when-to-call-directly, and explicit instruction for variants ("Use `variants: 2-3` for 'give me a few options' requests"). It also states when iterateOnFlowId applies versus when to use a different tool — genuine 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?

With no annotations, the description must carry the full behavioral burden. It does disclose the output (draft + builder URL) and the deprecated status, which adds context. However, it does not state whether the tool mutates state, requires any permissions, or has side effects. The description only hints at behavior through the draft/URL mechanism, leaving the safety and state-change profile ambiguous.

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

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

The description is concise overall, but it contains redundant deprecation text: '[DEPRECATED — migrate to a non-deprecated version of generate_flow] DEPRECATED — use generate_flow@2.0.0...' repeats 'DEPRECATED' unnecessarily. Otherwise, the structure is front-loaded with the critical deprecation note, and each sentence contributes to the usage decision. Minor redundancy costs a point.

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

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

The description covers the primary purpose and the deprecation alternative, which is essential. However, it does not explain the four parameters beyond the natural-language description, nor does it describe any prerequisites or permissions. Given the tool's simplicity and the fact that it is deprecated, the description is adequate but not thorough—an agent might need additional context on how to properly supply the account and platform identifiers.

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

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

Schema description coverage is 0%, so the description should compensate. It only mentions the 'natural-language description' input, which maps to the `description` parameter, but says nothing about accountId, platformUserId, or platform. The description does not explain the purpose or constraints of the other three parameters, leaving the agent to infer their meaning from the schema alone.

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

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

The description clearly states the tool generates a complete automation flow from a natural-language description and returns a draft plus a builder URL. It also differentiates itself from the successor version by explaining it is for MCP synchronous clients, which is a specific purpose that distinguishes it from other generation tools like generate_multiple_flows.

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

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

Explicitly tells the agent to use generate_flow@2.0.0 instead, and defines the exact condition under which this version should be used ('for MCP synchronous clients that can't consume two-phase tool resolution'). This is a clear when-to-use and when-not-to-use directive with an explicit 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?

With no annotations provided, the description carries the full burden. It discloses that flows are generated as background DRAFTs and 'nothing goes live', which is critical behavioral information. It also mentions the ≤10 split constraint. It doesn't cover permissions or error behavior, but the core non-destructive nature is clear. The 'background' hint implies asynchronous operation, which is helpful.

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 with no fluff. The first sentence states purpose and behavior; the second provides usage conditions, alternatives, and invocation guidance. All critical information is front-loaded, and every sentence earns its place.

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

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

For a bulk-generation tool with no output schema, the description covers the essential decision points: when to use, what it produces (drafts, ≤10), and how to invoke it. It lacks details on return format or failure modes, but these are not critical for selection and invocation. The description is sufficiently complete for an agent to act on it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the 'description' parameter content (user's own words, keywords, copy, links preserved) and noting accountId defaults to the selected account. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: bulk-building automations from a whole-setup description, splitting into up to 10 drafts. It explicitly contrasts with generate_flow for single automations, distinguishing it from siblings. The verb 'bulk-build' is specific and the resource (automations) is clear.

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

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

The description explicitly states when to use: ONLY for multiple automations described at once, and singles out generate_flow for a single automation. It also instructs to call this directly as the first action without whoami/context lookup, providing concrete guidance on invocation sequence.

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?

No annotations are provided, so the description carries the burden. It discloses that the tool returns aggregate data across all published posts and mentions the optional filters, but doesn't disclose details like whether it's read-only, rate limits, or what happens with no filters (defaults to last 30 days). The behavior is reasonably clear but not deeply transparent.

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

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

The description is two sentences, front-loads the core purpose and metrics, and ends with concrete usage examples. It's efficient and well-structured, though the usage examples could be slightly more concise.

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

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

For a read-only analytics tool with 3 optional parameters and no output schema, the description covers the main purpose, metrics, and filter options. It doesn't explain the default date range behavior or the exact response structure, but given the tool's simplicity and the presence of sibling tools for deeper analytics, it's reasonably 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 0%, so the description must compensate. It explains startDate/endDate as date range filter (YYYY-MM-DD) and platform as a filter, which adds meaning beyond the raw schema. However, it doesn't clarify whether both dates are required together, what the default range is, or the exact effect of each parameter beyond 'filter'.

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

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

The description clearly states the tool fetches aggregate analytics across all published posts, listing specific metrics (total impressions, engagement, post count, per-platform breakdown, last 30 days timeline). It distinguishes itself from sibling tools like get_post_analytics and get_content_insights by focusing on aggregate overview rather than individual post or content-level analytics.

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

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

The description explicitly provides usage examples ('how did my content perform last week?' / 'what's my engagement on Instagram?') and states the optional filters (date range, platform). This gives clear guidance on when to use this tool versus alternatives, though it doesn't explicitly name sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states 'Read-only' and lists the specific state information returned, preempting any assumption of side effects. However, it does not describe the output structure in detail (e.g., exact field names or formats), which a fully transparent description might, but the listed items suffice for most purposes.

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

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

The description is two sentences with no filler. The first sentence front-loads the purpose and enumerates the returned data; the second adds a critical usage exclusion. Every word earns its place, and the structure is highly scannable.

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 no parameters and no output schema, the description lists every major piece of state returned (on/off, review mode, posts/week, target-account count, pause reason, batch summary), giving the agent a clear expectation. It also provides context on when to avoid using it. The only minor gap is the absence of an explicit example of the batch summary format, but for a status getter this is adequate.

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 are zero parameters, so schema description coverage is effectively 100% and the baseline is 3. The description does not need to explain parameters because there are none; it appropriately focuses on output semantics instead. No additional parameter detail is required.

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

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

The description states a specific verb 'report' and enumerates exactly what it reports: on/off state, review mode, posts per week, target-account count, pause reason, and batch summary. It explicitly says 'Use ONLY' and contrasts with related tools, making it unambiguous and distinct from siblings like generate/adjust/approve/turn-on.

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

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

The description provides explicit when-to-use ('Use ONLY to report Autopilot's state') and when-not-to-use guidelines ('Do NOT call it before generate/adjust/approve/turn-on — those tools resolve the current week themselves'), naming the alternatives and the rationale. This gives the agent clear 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?

With no annotations, the description bears full burden. It discloses read-only behavior and return composition (static platform map + per-account list). It stops short of auth/scope details, but the list/static language resolves the main side-effect question.

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 concise, front-loaded sentences with zero filler and a natural move from purpose to usage to return shape.

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

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

For a read-only single-parameter tool, it covers purpose, usage, and return shape adequately. However, missing accountId semantics and the close list_capabilities sibling leave an agent guessing on edge cases.

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

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

Schema coverage is 0% and accountId is never named in the description. The phrase 'per-account list' implies account filtering, but the optional accountId's behavior (default/all vs single account) is left to inference.

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: lists per-account capabilities and contrasts automation vs scheduler. It is clear, but with a sibling named list_capabilities it does not explicitly differentiate itself.

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 concrete triggering user questions ('can my Twitter account run automation?'). It lacks explicit when-not-to-use or alternatives, but gives clear selection context.

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

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

With no annotations present, the description carries the full behavioral disclosure burden. It adds an important, non-obvious privacy behavior: actual collected values are not exposed to the LLM, only metadata. This is genuinely useful beyond the schema. It does not explicitly state read-only/no-side-effect behavior, but the 'get' name and summarizing language imply it.

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 with no wasted words. The first sentence front-loads the core capability and the privacy constraint; the second gives direct user-query examples. The structure is scannable and every phrase earns its place.

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

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

For a summary tool with no output schema, the description usefully states what the response includes (count, field-type breakdown, recent submission metadata) and the critical privacy limitation. It omits exact response formatting and error behavior, but neither is essential for an agent to invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: 'flow' maps to the required flowId, 'breakdown by field type' maps to fieldType, and 'last N submissions' maps to limit. It does not spell out parameter names, defaults, or enum details, but an agent can infer the parameter roles from the prose.

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

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

The description clearly identifies the action ('Summarize') and the resource ('data collected by a flow'), then enumerates the exact outputs: total count, breakdown by field type, and last N submissions. This distinguishes it from siblings like get_flow_stats or summarize_flow_purpose by focusing on a data-collection summary rather than flow stats or purpose.

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 concrete, human-language trigger examples ('how many emails has my flow collected?' / 'what data did this flow gather?'), making the intended use case explicit. It does not name sibling tools or state when not to use it, which keeps it from a 5, but the usage context is clear.

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

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

With no annotations, the description carries the full burden. It discloses a notable behavior: returning 'insufficient_data' below the statistical floor, and it notes that insights come 'with sample sizes'. It reasonably implies a read-only analytics operation, though it does not detail response format.

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: first identifies the tool's outputs, second gives direct usage guidance, third reveals an important edge-case behavior. Every sentence earns its place and the front-loaded verb makes the purpose immediately clear.

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 one optional parameter and no output schema, the description covers the key outputs, intended questions, and an important statistical caveat. The main gap is that the 'weeks' parameter's effect is left completely unspecified.

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

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

Schema description coverage is 0%, and the description never mentions the only parameter, 'weeks'. The schema's min/max defines the range, but the description adds no meaning about what weeks controls (e.g., lookback window or period granularity).

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

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

The description uses a specific verb ('Get') and resource ('this account's content performance insights') and then enumerates the exact dimensions analyzed: formats, days of week, content pillars, and top/bottom posts. This level of specificity distinguishes it from broader analytics siblings like get_analytics_overview.

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

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

It explicitly states when to use the tool: for 'what's working', 'when should I post', and 'what content performs best'. However, it does not mention when not to use it or name alternative tools for overlapping analytics needs.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the return payload in substance (steps, connections, and what stops the flow running) as well as the read/non-mutating framing implied by "Fetch". It stops short of stating auth requirements, rate limits, or error behavior, so it is not exhaustive for an annotation-free tool.

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

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

Front-loaded with the core action, then progressively adds intent examples, exclusion guidance, and a return summary; no sentence is filler. It is dense and slightly run-on with the quoted intent phrases, which costs a point but keeps the routing information compact.

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 read tool with no output schema and no annotations, the description covers what the agent needs: what it returns, which parameter narrows the result, how to obtain the id in the common page context, and which sibling to use for write intents. Nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: flowId is explained contextually (already present in <page_context> on a flow page) and nodeId is explained as accepting an id OR a name and returning a single step's data. That resolves the most likely ambiguity, though it doesn't cover formatting or failure modes for an invalid 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 ("Fetch one flow by id") and immediately scopes it against siblings by enumerating the user intents it serves: seeing, inspecting, opening, and checking configuration/triggers. An agent can distinguish this from list_flows, search_flows, and get_flow_stats without opening any schema.

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

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

Gives explicit when-to-use with natural-language user phrasings ("what does this flow do", "show me the welcome flow"), plus an explicit when-NOT-to-use: it is not a lookup before an edit, and edit requests should go to the write tool instead. It also tells the agent that on a flow page the id is already in <page_context> and can be passed directly.

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

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

With no annotations, the description carries the behavioral transparency burden. It discloses the ordering (newest-first), the default/max limit, and the content of each returned row (version number, creation time, creator, summary). It does not discuss auth, errors, or side effects, but 'List' and 'Returns' make the read-only nature clear.

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

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

The description is three concise sentences with no filler. It front-loads the core purpose, then provides output behavior and usage guidance. Every sentence adds value.

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

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

Given the simple two-parameter tool and no output schema, the description covers purpose, return content, ordering, limits, and usage. Minor gaps remain: it does not specify what happens with an invalid or unknown flowId, nor explicitly connect to the revert_flow_to_version sibling for the actual revert action.

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

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

Schema description coverage is 0%, so the description must add parameter meaning. It explains that limit controls 'the most recent N revisions' with default and max, and that the tool operates on 'a flow' identifying the flowId. This adds useful semantics beyond the bare schema types.

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

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

The description uses a specific verb and resource: 'List the version history of a flow.' It clearly distinguishes this from related siblings like get_flow and get_flow_stats by focusing on historical revisions, and even ties it to user intent ('show me what I had before').

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

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

The description explicitly states when to use the tool: 'Use this when the user asks "show me what I had before" or wants to revert.' This gives clear context, though it does not mention alternatives such as revert_flow_to_version or exclude cases where the user wants the current flow state.

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?

No annotations are provided, so the description bears full responsibility for disclosing behavior. While it states the data returned, it does not mention that the operation is read-only, what happens if the flow ID is invalid, or any error conditions. It also gives no indication of latency or rate limits. For a simple analytics fetch, more behavioral context (e.g., 'does not modify the flow') would be expected.

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

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

The description is two sentences with no redundancy. The core capabilities are front-loaded in the first sentence, and the second provides practical example user intents. Every sentence adds value without 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?

Given the tool has a single parameter and no output schema, the description lists the metrics returned, which is useful. However, it does not describe the structure of the response (e.g., object vs array, field names) or how the 'last 7 days daily timeline' is represented. It also lacks any notes on prerequisites or edge cases. The description is adequate for a basic use case but leaves some questions unanswered.

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

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

The schema describes flowId only as a string with 0% coverage, so the description must compensate. The description implies flowId identifies the flow but does not explain where to find it, its format, or any constraints (e.g., must be a valid flow ID). For a single undocumented parameter, the description underdelivers; an agent might not know how to obtain or validate flowId.

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

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

The description clearly specifies a verb ('Fetch') and resource ('execution analytics for one flow') and enumerates the exact metrics returned (total triggers, button clicks, unique users, status breakdown, daily timeline). It distinguishes from sibling tools like list_flows_with_stats (which suggests multiple flows) and get_analytics_overview (broader analytics). The scope is unambiguous.

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

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

The description provides concrete user intents when to use it, such as 'how is my welcome DM performing?' and 'is the flow getting any traffic?'. It implies the tool is for a single flow's analytics, which differentiates it from list-oriented siblings, but it does not explicitly state when not to use it or mention alternatives. The guidance is clear but lacks explicit exclusion criteria.

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

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

With no annotations provided, the description carries the behavioral burden and does substantial work: returns one MediaItem, no picker/table, throws not_found, and pipes mediaId downstream. It could go further by stating explicitly that the operation is read-only and what happens if the account is invalid, but it is still well beyond minimum.

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

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

Dense, front-loaded, and purposeful. The primary purpose appears first, and every sentence adds information about routing, return shape, errors, filters, or downstream usage, 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?

The description covers purpose, routing, return shape, errors, and downstream integration, which is strong given no annotations and no output schema. It is slightly incomplete because accountId semantics are missing and the MediaItem structure is only implied via mediaId.

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 schema description coverage is 0%, so the description must explain all parameters. It explains mediaType well, including its enum values and narrowing behavior, but accountId is never explained, including whether it selects the live account, whether it is required, or what its default is.

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

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

The description clearly identifies the operation: resolving exactly one most recent published media item for a singular user intent. It also distinguishes itself from siblings like list_scheduled_posts and list_published_media, so an agent can distinguish without inspecting schemas.

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

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

Explicitly states when to use this tool (singular live-account intent, flow triggers) and when not (bare 'my most recent post' with no platform cue → list_scheduled_posts; browsing multiple → list_published_media). This gives the agent concrete routing rules.

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, so the safety profile is covered. The description adds no additional behavioral context such as what 'check' entails, whether it makes a network call, or what side effects (if any) occur beyond the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It quickly communicates the action and the conditions for use, making it efficient and easy to parse, though it could be slightly more structured with a separate usage note.

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

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

The description gives clear usage guidance but does not explain what the tool returns or what happens after 'checking' for tools. With no output schema present, the description carries the burden of explaining the result, which it fails to do. For a simple one-parameter tool, this is a notable gap, though not severe.

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

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

Schema coverage is 100%, and the single parameter 'context' is already documented with a clear description in the schema. The tool description adds no additional semantic meaning beyond what the schema provides, which aligns with 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?

The description clearly states the tool's function: checking for additional tools when a task could benefit from specialized capabilities. It distinguishes itself from the sibling clipform_* tools by being a meta-tool for tool discovery rather than a domain-specific operation, though it does not explicitly name this distinction.

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

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

The description provides explicit usage guidance: use this tool whenever specialized capabilities might help, even if existing tools could work as a fallback. This gives the agent a clear decision rule, though it does not mention when not to use it or list alternative tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It tells the agent that the tool returns install snippet plus instructions, and that it returns create-one-first instructions when no pixel exists, which is a meaningful edge-case behavior. It does not explicitly state the read-only nature, but this is strongly implied by 'get' and the nature of the 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?

The description is two sentences with zero filler. It front-loads the primary purpose and resource, then immediately gives usage context and the edge-case behavior. Every word adds value.

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

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

For a zero-parameter, no-output-schema tool, the description covers the essential aspects: what it does, when to use it, and behavior when no pixel exists. It could have been slightly more explicit about the structure of the returned instructions, but the information needed to invoke the tool correctly is present.

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

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

The tool has 0 parameters, so the baseline score is 4. The description correctly avoids mentioning parameters since there are none. No additional parameter-level explanation is needed because there is nothing 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?

The description clearly states a specific verb 'Get' and a concrete resource: 'the user's SociaHive Pixel install snippet + instructions'. It also explicitly ties the tool to common user intents ('install the pixel' / 'track events on my site'), making it easy to distinguish from any sibling tools that might handle related but different tasks.

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

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

The description gives explicit when-to-use guidance via the quoted phrases 'install the pixel' and 'track events on my site'. It does not mention when not to use it or name alternative tools, but the provided context is sufficiently clear for an agent to decide when to invoke this tool.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly states key behavior: one row per platform target, and an empty list when the post has no analytics yet. It does not cover errors, auth, or failure modes, but the core read behavior is transparent.

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 concise sentences with no filler. The main action is front-loaded, metrics are listed compactly, and the empty-list edge case earns its place.

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

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

For a single-parameter tool with no output schema, the description covers normal invocation, return shape, and an important edge case. It omits error behavior for invalid post IDs or permission failures, but nothing essential to a basic correct call is missing.

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

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

The description implies that postId identifies a single published post, which adds some meaning beyond the bare schema property. But it never explicitly describes postId, its format, or where to source valid post IDs. Since schema description coverage is 0%, this is only partial compensation.

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

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

The description names a specific operation ('Fetch'), a clear resource ('per-platform analytics for one published post'), and enumerates the exact metrics returned. This scopes it away from broader siblings like get_analytics_overview or get_content_insights.

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

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

It gives explicit user-phrase triggers ('how is my post performing?' / 'show me stats on this post'), so an agent knows when to use it. However, it does not name alternative tools or state when not to use it, so it falls just short of full 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that the full caption is returned without truncationable, and that `not_found` is returned if the media ID doesn't belong to the currently selected account. These are concrete, non-obvious behaviors. It doesn't describe authentication or error details, but the disclosed conditions are genuinely useful for an agent.

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

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

The description is front-loaded with the main action and key parameter, and most sentences add distinct value. The bold 'Platform-published, not scheduler-side' and the later 'For scheduler-side posts use `get_scheduled_post`' are slightly redundant, and the error behavior is placed at the end. Overall it is compact but not perfectly minimal.

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 single-fetch tool with no output schema, the description covers the main parameter, the domain distinction, an alternative tool, and an important error condition. A small gap is the lack of explanation for the optional `accountId` parameter, and the return value is only partially described via the full-caption note. Still, an agent can confidently call this tool for the intended use case.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `mediaId` as the platform's own ID with an example (Instagram's media id). However, `accountId` is left unexplained, despite being an optional parameter; the reference to 'currently selected account' gives a hint but not a full semantic. Given one parameter is well-annotated and the other is absent, a 4 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 begins with a specific verb and resource: 'Fetch a single platform-published media item by its `mediaId`'. It also clearly distinguishes this from scheduler-side posts, and the example 'Instagram's media id' makes the resource concrete. The wording differentiates it from list/search siblings and from get_scheduled_post.

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

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

The description explicitly states when to use this tool: when you need a platform-published media item by its platform ID本期, not a scheduler-side post. It names `get_scheduled_post` as the alternative for scheduler-side posts, which is a clear routing signal. It does not contrast with `get_latest_published_media` or `search_published_media`, but the mediaId-based lookup makes the use case reasonably obvious.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the returned payload (full text, recurrence, status detail, comment automation) and the important scheduler-side vs platform-published distinction. It does not cover auth requirements or error behavior (e.g., what happens for a missing/invalid id), which is a modest remaining gap for a read tool.

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

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

Front-loaded with the core action and scope, then the usage routing, then the return contents. Every sentence earns its place; slightly dense but no waste.

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

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

No output schema exists, so the description correctly covers return contents (text, recurrence, status, comment automation) and the scope boundary. Only the postId provenance/format and error behavior are 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?

One parameter (postId) with 0% schema description coverage, so the description must compensate. It says 'by id' and implies the id originates from list_scheduled_posts, but gives no id format or provenance detail. Adequate, not rich.

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 (fetch) and resource (one scheduler-side post by id) and explicitly scopes it to drafts/queued/recurring/scheduler-published. It also distinguishes itself from two siblings by name (list_scheduled_posts, get_published_media), so an agent can tell exactly what this tool returns versus those.

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

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

Explicit when-to-use ('Call AFTER list_scheduled_posts when the user references a specific scheduler entry') and when-not ('For platform-published media use get_published_media'). The alternative and the selection condition are both named.

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

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

With no annotations, the description carries the transparency burden and discloses key behaviors: date-range requirement, ISO 8601 format, and the 200-post cap. It does not explain what happens past the cap (truncation vs. error) or the return structure, but the core behavioral traits are clearly conveyed.

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 earning its place: scope, exclusion, example use cases, date format, and limit. The primary action is front-loaded in the first sentence, and there is zero filler.

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

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

For a read-only list tool with no output schema, the description gives enough for an agent to call it correctly: required date range, format, cap, and the semantic distinction from published posts. The only real gap is the 'platform' parameter and post-cap behavior, which are secondary for basic invocation.

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

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

Schema coverage is 0%, so the description must compensate. It adds essential format semantics for fromDate/toDate via 'Pass ISO 8601 dates,' but the optional 'platform' parameter is never explained, leaving the agent to guess its purpose. This makes the description only partially effective for parameter understanding.

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

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

Description uses a specific verb and resource ('Get scheduler-side posts') with a clear date-range scope, immediately distinguishing it from platform-published media tools. Example natural-language queries reinforce intent. The explicit 'Scheduler-side, not platform-published' contrast prevents confusion with sibling tools like list_published_media.

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

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

The description explicitly states when to use it ('Use for...') with concrete query examples and gives a clear when-not boundary ('not platform-published'). However, it does not name specific alternative sibling tools, relying on the sibling list context instead, so it falls just short of fully 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?

No annotations are provided, so the description carries the full burden. It discloses the return fields (id, platform, username, status) and adds a security-relevant detail ('never tokens'). It also clarifies it is not a preflight check, preventing misuse. It does not explicitly state it is read-only, but 'List' implies no side effects; a minor gap given no annotation support.

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

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

The description is efficiently structured: it starts with the core purpose, then usage constraints, and ends with return info. Every sentence adds value, and the negative example is front-loaded. Despite its length, it remains tight and scannable.

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 there is no output schema and no annotations, the description provides crucial context: what it returns, that it never returns tokens, and when not to use it. It could be more complete by explaining how to use the parameters, but the core information an agent needs to invoke it correctly is present.

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

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

The schema description coverage is 0%, so the description must explain the parameters, but it does not. It never mentions the 'status' filter (beyond the enum in schema) or the 'platform' filter. The parameter names are somewhat self-explanatory, but the description adds no guidance on how to use them, such as filtering by platform or status. This is a significant gap for a tool with two optional parameters.

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

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

The description opens with a clear verb-resource pairing ('List the user's connected social media accounts') and names example platforms. It explicitly differentiates itself from action tools by explaining that a platform mentioned inside an action is the action's target, not this tool's concern. This makes the purpose unmistakable and distinct from siblings like publish_post_now or disconnect_account.

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

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

The description provides explicit usage guidance: 'Use ONLY when they ask which accounts they have or whether a platform is connected.' It also gives a clear negative rule with an alternative: 'NOT a preflight... call the action tool.' This leaves no ambiguity about when to select this tool versus an action tool.

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

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

No annotations are present, so the description carries the burden. It discloses the filtering basis and adds a key behavioral rule ('the tools you can see are the tools you have'), making clear there is no hidden capability-check side effect. It doesn't mention output format, but that is minor for an introspection 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?

Two sentences front-load the purpose and then the guardrail. No filler or redundant restatement.

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, low-complexity introspection tool, the description covers what it returns, when to call it, and when not to call it. It could have named get_capabilities/get_more_tools as siblings for disambiguation, but that is not required for correct invocation.

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

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

The tool has zero parameters, so the baseline is 4; there is nothing for the description to add beyond 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 specific verb ('Returns') and a clear resource: the per-user list of available tools, filtered by tier and flags. It does not explicitly contrast itself with the similarly named sibling get_capabilities, so it narrowly misses full sibling differentiation.

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

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

Explicitly says use ONLY for the literal 'what can you do?' request and explicitly forbids using it as a preflight check. This is strong, unambiguous 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?

No annotations are provided, so the description carries the full burden. It reveals the tool is a read operation (list) but does not disclose behavioral traits such as sorting, pagination, or whether it returns only active or all evergreen items. It also doesn't mention if it requires authentication or what happens to cleared items.

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

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

The description is concise, one sentence, and front-loads the main purpose. The quoted example usage is slightly redundant but harmless. It earns a 4 for its efficiency.

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

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

Given the tool is a list operation with no output schema, the description should convey more about the returned data (e.g., fields like post ID, status, creation date) and any limitations (e.g., rate limits). It only tells the agent that it lists the queue, leaving the agent uncertain about the response format, which is a significant gap for a 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 input schema has no parameters, and the schema coverage is 100% (vacuous). The description appropriately explains the purpose but doesn't need to add parameter semantics because there are none. Baseline 4 for zero-parameter tools is justified here.

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

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

The description clearly states it lists the user's evergreen queue, using a specific verb and resource. However, it does not explicitly distinguish it from the sibling add_to_evergreen or other list tools, though the evergegreen queue is a distinct concept in this context.

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 primarily echoes the query phrase 'what's in my evergreen queue' but gives no guidance on when to prefer this over alternatives like list_scheduled_posts, nor does it mention any prerequisites or exclusions. It implies usage for viewing the queue but lacks 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?

No annotations are given, so the description carries full burden. It discloses the return fields (id, name, status, etc.) and pagination behavior (nextCursor usage). It also notes to call get_flow for full detail, implying this is a lightweight list. While it doesn't describe side effects (none expected), it gives enough behavioral context for an agent to call correctly. Minor gap: doesn't mention that the list may be filtered by status, but that is implied via the enum.

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

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

The description is longer than typical but every sentence carries utility: purpose, usage, return fields, examples, pagination advice. It is front-loaded with the primary purpose and uses clear separations. Slightly dense but not verbose. A 4 reflects that it is well-structured and efficient despite its length.

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 list tool with 5 parameters, no output schema, and no annotations, this description is exceptionally complete. It explains return fields, pagination, sorting strategies, and the relationship to sibling tools. There are no missing pieces an agent needs to invoke the tool correctly. The only minor omission is a note on error handling, but that is not expected for a simple read operation.

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

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

Schema description coverage is 0%, so the description must compensate. It provides concrete usage for sortBy/sortOrder/limit (e.g., 'For the oldest flow pass sortBy: "createdAt", sortOrder: "asc", limit: 1'), explains cursor for pagination, and advises 'Use limit aggressively'. It does not explicitly explain the status parameter, but the schema's enum (draft, published, all) is self-explanatory and the text mentions 'active/draft work'. Overall, it adds value well beyond the bare schema.

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

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

The description states a specific verb ('List') and resource ('the user's automation flows'), and explicitly scopes it to BROWSING many. It distinguishes from siblings by clarifying it is NOT a lookup step and names alternatives (get_flow / search_flows, bulk tool). This is clear and differentiated.

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

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

Provides explicit when to use: "Use when the user asks 'what flows do I have?' or wants a recap of active/draft work." Also tells when not to: "NOT a lookup step: for ONE named flow use get_flow / search_flows; to CHANGE several at once use the bulk tool." This is a model example of usage guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the operation is a server-side join, sort, and limit, and it states the default behavior ('top 10 published flows by triggers, descending'). It does not explicitly state the return shape or that no data is mutated, but for a read-style list tool the core behavior is well communicated.

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

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

The description is compact and front-loaded: it opens with the core purpose, then gives usage phrases, then the routing rule, then defaults. Every sentence adds value, and there is no repeated schema information or filler.

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

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

For a tool with no output schema and no annotations, the description covers the essential information for selection and invocation: purpose, metrics, defaults, and when to prefer it over siblings. The main remaining gap is the lack of an explicit statement about the response structure or fields, but the tool name and ranking semantics make the output reasonably predictable.

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

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

Schema description coverage is 0%, so the description must compensate. It enumerates all metric options (triggers, completions, unique_users, button_clicks) and maps defaults for limit, metric, status, and sortOrder in one sentence. It does not name parameters explicitly, but the semantics are clearly inferable from the use cases and defaults.

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

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

The description uses a specific verb ('Rank') and resource ('flows'), enumerates the exact metrics, and gives concrete user intents like 'top N flows by X' and 'flow leaderboard'. It also distinguishes itself from list_flows/get_flow_stats by naming the preferred workflow, so an agent can select it correctly.

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

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

The description explicitly lists when to use the tool ('Use for "top N flows by X"', 'best/worst performing flows', 'rank my flows', 'flow leaderboard') and gives a direct routing rule: 'ALWAYS prefer this over list_flows + multiple get_flow_stats calls'. This is clear, actionable guidance with no ambiguity.

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

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

With no annotations, the description takes on the full burden. It discloses returned fields (mediaId, mediaType, truncated caption at 200 chars, permalink, thumbnail, postedAt), recency sorting, and the platform-published vs. scheduler distinction. It does not cover auth, rate limits, or pagination behavior, but the core behavioral traits an agent would need are clearly present.

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

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

The description is dense but every sentence adds value: purpose, intent qualifier, return fields, sibling differentiators, and platform scope. It front-loads the main purpose and uses bolded cues ('Browse intent only', 'Platform-published') to highlight key distinctions. No filler or redundancy.

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

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

Given no output schema and no annotations, the description covers the essential aspects: return fields, sorting, truncation, platform scope, and alternative routing. It omits pagination and error behavior, but for a list tool with optional filters and a clear sibling set, the provided context is nearly sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters (limit, accountId, mediaType). It does not explain that limit controls the count, accountId selects an account, or mediaType filters by post/reel/story/carousel. The parameter names are somewhat self-explanatory, but the description adds no semantic value beyond the bare schema, leaving a notable gap.

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 ('List recent media on the user's connected platform'), explicitly scopes to browse intent, and immediately distinguishes itself from siblings like get_latest_published_media, get_published_media, search_published_media, and list_scheduled_posts. An agent can reliably select this tool versus alternatives.

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

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

Provides explicit when-to-use guidance with concrete examples ('show my recent reels'), plus clear exclusion criteria for singular intent, known mediaId, caption search, and scheduler-side items. This is model guidance for routing between the closely related list/get/search tools.

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

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

No annotations are provided, so the description carries the full burden. It clearly marks this as scheduler-side/read-only, notes that it returns only a summary payload, explains superlative handling via sortOrder and limit, and describes pagination with nextCursor/cursor. It also discloses the prerequisite behavior: call it directly without listing accounts first.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then adds exclusions, alternatives, return shape, and operational patterns without redundancy. Emphasis and line breaks make the long content scannable.

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

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

For a read-only list tool with no output schema and no annotations, the description is unusually complete: it names the returned fields, explains pagination, gives superlative patterns, and routes all relevant sibling cases. The only minor omission is the platform parameter, but the parameter name plus the rest of the guidance make the tool safe to invoke.

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

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

With 0% schema description coverage, the description must compensate. It does well for sortOrder ('asc' oldest, 'desc' newest), limit (with sortOrder for superlatives), and cursor (pass previous nextCursor). However, it never explains the platform filter parameter and only loosely maps status values to the schema enum, so it is not a perfect 5.

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

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

States a specific verb and resource: 'List posts from the SociaHive Content Scheduler' and scopes it to drafts, queued, recurring, and published-via-scheduler entries. It also distinguishes from platform-published content and names the returned fields, so there is no ambiguity about what this tool 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?

Explicitly lists when to use it ('what's scheduled this week', 'show my drafts', failed publications, queue-side history) and when not to use it. It names direct alternatives: write/bulk tools for changes, list_published_media for platform-side posts, and get_post for full content, and even says not to call list_accounts/whoami first.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does communicate that the operation is read-only ('Browse', 'Returns names + descriptions') and what the result will contain. However, it does not disclose pagination behavior, default limits, or how category filtering behaves, which are relevant because of the limit/cursor/category parameters.

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

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

The description is two sentences with no filler. The core purpose and examples are front-loaded, followed by usage trigger, output summary, and next-step routing. Every sentence earns its place.

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

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

For a simple browse/list tool with zero required parameters and no output schema, the description conveys the essential purpose and output contents. Gaps remain around pagination, the meaning of category filtering, and the effect of limit/cursor. The next-step pointer to duplicate_flow is helpful, but the completeness is only adequate, not rich.

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

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

Schema description coverage is 0%, so the description must compensate for the three undocumented parameters. It provides example categories (welcome messages, lead generation, customer support) which loosely map to the category parameter, but it never explains limit, cursor, or category semantics. The parameter names are self-explanatory, but the description adds no explicit value on top of 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?

The description uses a specific verb ('Browse') and a clear resource ('pre-built system flow templates'), with concrete examples like welcome messages and lead generation. It is clearly distinguishable from sister tools like list_flows and generate_flow, and it establishes a bridge to duplicate_flow for next steps.

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

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

The description explicitly says 'Use when the user says...' and provides two example utterances, making the triggering context clear. It also mentions cloning via the templates UI or duplicate_flow once selected, giving a path forward, though it does not explicitly say when not to use this tool in favor of list_flows or search_flows.

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

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

With no annotations, the description carries the behavioral burden and explicitly flags irreversibility, a confirmation requirement, and per-platform outcome recording. This is valuable for a potentially destructive publish action, though it does not discuss failure modes or authentication/permission requirements.

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-load the essential action and then add the critical warnings. There is no filler or repetition of schema details.

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

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

For a two-parameter tool, the description is largely sufficient: it identifies the object, target, timing, irreversibility, and per-platform outcome. It could be more complete by noting how confirmation is obtained or what the response format is, but the sibling ambiguity is the main 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?

At 0% schema description coverage, the description compensates by explaining that postId refers to a prepared post and platforms are the targets, with a published-outcome recorded per platform. It leaves detailed enumeration to the schema's platform enum, which is appropriate.

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

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

The description names a specific verb ('Publish'), resource ('prepared post'), identifier (postId), and target ('platforms'), and adds the per-platform outcome. It is clear on its own, but it does not distinguish itself from the near-identical sibling 'publish_post_now'.

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 context is implied: the post must already be prepared and the action should only happen after confirmation because it is irreversible. It does not explicitly state when to choose this tool over alternatives such as schedule_post or publish_post_now, so an agent must infer selection criteria.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the most critical traits: the operation is IRREVERSIBLE, cannot be un-published, and requires confirmation. It also clarifies that publication goes to all configured platforms, which is an important side effect for an agent to know before calling.

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

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

The description is compact and front-loaded with the primary purpose, followed by the critical warning, usage trigger, and parameter guidance. The quoted trigger phrases add some redundancy but are useful for intent matching in an agent context, so the overall length is still justified.

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-optional-parameter tool with no output schema and no annotations, the description covers the essential operational details: what it does, when to use it, its irreversible nature, the confirmation requirement, and how to identify the target post. It leaves minor gaps around return behavior and precedence if both postId and postName are supplied, but an agent can call it correctly with the provided information.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It does this meaningfully by explaining that postName is the caption/opening words and can be used as a fallback when no id is available, indirectly distinguishing postId from postName. It does not fully define postId or address what happens when both are omitted, but the core identification strategy is clear.

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

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

The description names a specific verb ('Publish'), resource ('a post'), immediacy ('immediately'), and scope ('to all configured platforms'), which clearly differentiates it from deferred scheduling tools like schedule_post. The explicit irreversible warning reinforces the operation's nature without obscuring what it does.

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

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

The description provides clear contextual cues for when to invoke it ('publish this now', 'post immediately') and includes a prerequisite ('Requires confirmation'). It does not explicitly name alternatives or when-not-to-use conditions, but the immediate-publish scope makes the intended usage 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?

With no annotations, the description carries full disclosure burden and does disclose two key behaviors: conditional execution ('only when confident, else leaves it for a human') and side effect ('Records a resolved-outcome on success'). It also makes clear this is a mutating action. It omits authentication, reversibility, and the operational meaning of 'confident', so it is not fully transparent.

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 no filler; the main purpose is in the first clause. The confidence condition and outcome recording are each given their own sentence and earn their 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?

The tool has no annotations, no output schema, and 0% parameter documentation, so the description must carry more weight. It covers purpose and high-level side effects but not the meaning of the required 'message' parameter, the response/return behavior, or the criteria for confidence. That is insufficient for a mutation tool with two required inputs.

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

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

Schema description coverage is 0%, so the description must explain both parameters. It gives sessionId context ('by sessionId'), but says nothing about what 'message' should contain or how it is used. This leaves the primary required input semantically underdocumented.

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

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

States a specific action ('Auto-resolve'), a precise resource ('support conversation'), and an explicit identifier ('by sessionId'). The 'Resolves only when confident' clause further differentiates behavioral scope, and none of the sibling tools overlap with this support-resolution operation.

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 conditional behavior makes clear this tool is the automated attempt at resolution and that human follow-up remains if confidence is low. It does not explicitly name alternatives or say 'use when X', but the context is sufficiently clear among unrelated siblings. Missing explicit exclusions is the only gap.