FlowCastle

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

Annotations already declare destructive=true and idempotent=false, but the description goes far beyond: it enumerates the destructive action kinds, explains what delete_operation and delete_broadcast additionally remove (hidden graph flow, run history, delivery history), describes run_operation's real, unrecallable side effects, and documents the non-atomic mid-batch failure model with `reverted`/`errorClass: partial_write` semantics.

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

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

It is long and dense, but the tool is exceptionally complex and the highest-value facts (single write path, no separate validate, DESTRUCTIVE warning, irreversibility, draft-not-published) are front-loaded. A few clauses on broadcast recipes could be trimmed or deferred to get_action_schema, but almost 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?

With no output schema, the description compensates by enumerating the return shape (success, validated, reverted, errorClass, changes, errors, warnings, actionId, idRemap) and clarifying the critical draft-vs-published boundary (deploy_application required to go live). Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema, including placeholder ids and the action enum. The description reinforces the placeholder-id/idRemap mechanic but adds no new parameter-level detail beyond what the schema carries, so the baseline 3 applies.

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

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

States a specific verb+resource ('Validate and apply a batch of flow-builder actions') and immediately scopes it as 'the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders.' This distinguishes it cleanly from the read-only siblings (get_action_schema, get_flow_context) and from validate_actions.

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

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

Explicitly says 'Call this directly; a separate validate_actions call beforehand is unnecessary', names the sibling it replaces, and routes to get_action_schema and get_design_guidelines for prerequisites. It also gives concrete when-to-use recipes for broadcasts (create_broadcast draft vs. update_broadcast with status SCHEDULED).

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

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

Annotations only provide generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds critical behavior: failure on duplicate platformId (409), the botId omission rule, the variables map using names not ids (422 on unknown names), and a nuanced idempotency statement ('NOT idempotent: retrying a success creates nothing new only because the duplicate platformId is rejected'). This goes far 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?

Four dense sentences cover purpose, use cases, permission, constraints, error behavior, and idempotency. Each sentence earns its place; no filler or repetition. The front-loaded purpose sentence immediately orients the agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 10 parameters, a nested variables object, no output schema, and only minimal annotations, the description covers permission, failure modes, parameter constraints, and idempotency nuances. It does not describe the return value or pagination, but for a create operation this is less critical and may be supplemented by schema. The description is appropriately complete for the tool's complexity.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema for several parameters: platformId must be unique (and duplicate fails), botId may be omitted only with a single-bot app, variables keys are names/paths not ids and fail with 422, and applicationId can fail with MCP_APPLICATION_REQUIRED. This is substantial added value for the most error-prone 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 specific verb and resource: 'Create a contact manually — for imports or externally-sourced audiences'. It clearly distinguishes this tool from the automatic contact creation triggered when a bot receives a message, and the sibling list (e.g., update_contact, get_contact) makes the scope unambiguous.

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

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

The description explicitly states when to use the tool ('for imports or externally-sourced audiences') and when not ('contacts who message a bot are created automatically'). It also mentions a required permission (manage_broadcasts) and key constraints (platformId uniqueness). However, it does not explicitly name an alternative tool for updating existing contacts, so it falls just short of a 5.

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

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

Goes well beyond the annotations: it explains the consequence of non-idempotency ('calling it twice creates two reminders'), that it creates persistent state, that nothing fires on the due date, that a contact reply does not close it, and that assignment depends on key type (personal vs workspace). Annotations only flag idempotentHint=false and readOnlyHint=false; the description supplies the operational meaning.

Agents need to know what a tool does to the 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 four tight clauses each carrying a distinct behavioral fact (persistence, non-idempotency, no-send, close semantics, assignment). 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?

No output schema exists, but the description covers what an agent needs: lifecycle, delayed/no delivery, closing rules, and ownership semantics. For a mutation tool with zero destructive hint and 100% schema coverage, nothing material is missing.

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

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

Schema description coverage is 100%, with dueAt, contactId, reasonCode, reasonText and applicationId all documented in the schema, so the baseline is 3. The description's final sentence on key-scoped assignment restates behavior already covered by the applicationId schema description, adding no new parameter syntax or constraints.

Input schemas describe structure but not intent. Descriptions should explain 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 follow-up reminder for a person to get back to a contact.' It immediately distinguishes itself from the send/automation siblings by declaring it is 'a to-do, not an automation' and naming send_message and broadcast as the 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?

Explicitly says when NOT to use it ('Nothing is sent when it comes due — use send_message or a broadcast to actually message someone') and clarifies it is distinct from the automatic 'no reply for N days' follow-ups. Both the routing condition and the exclusion are stated, not 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?

The description discloses critical runtime behavior beyond annotations: delivery is asynchronous, 'queued' means handed to the queue rather than confirmed restarted, and a version may be marked published before any runtime receives it. It also covers idempotency ('Safe to repeat'), permission requirements, and the impact on real users. No contradiction with annotations is 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 long but densely informative; every sentence contributes either behavioral caveats, usage timing, return-value semantics, or permission requirements. It is front-loaded with the core purpose and then logically expands into when, how, and what to check.

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

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

Given the tool's complexity, asynchronous delivery, and lack of an output schema, the description fully compensates by enumerating the return fields, telling the agent to check error and per-bot status, and covering permissions, idempotency, and safety. Nothing needed for correct invocation or result interpretation is missing.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds useful semantic context by clarifying that botIds publish to a subset and that the 'ACTIVE version' goes to every active bot, which complements the schema's detailed explanations without redundantly repeating 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 states a specific verb and resource ('Publish the workspace to its bots') and immediately anchors it as 'the API equivalent of the dashboard's Deploy button.' It also explicitly differentiates from a sibling by saying apply_actions writes to the DRAFT graph, so an agent can tell exactly what deploy_application 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 gives explicit timing guidance: 'Deploy after a batch of edits (and after run_flow_autotest passes), not after every single action.' It also states what is deliberately not supported (rolling back is a dashboard action) and requires user confirmation before publishing unreviewed edits, which strongly signals appropriate usage.

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

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

The description goes well beyond the annotations by disclosing async behavior via requestId, the polling lifecycle, the manage_broadcasts requirement, no side effects on Telegram content, a 60-second deadline, shared read limits, persistent flood cooldowns, sponsored-ad caching, and that returned content must be treated as untrusted data. This is rich behavioral context that annotations alone do not provide.

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

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

Every sentence earns its place. The description is front-loaded with the core purpose, then flows logically through schema lookup, return/polling behavior, permissions, safety, constraints, and data trust. It is dense but not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, it fully describes the response pattern (requestId + polling) and all operational constraints: concurrency, deadline, rate limits, cooldowns, caching, and data trust. The nested input object is handled by directing the agent to the authoritative sibling tool rather than duplicating schema content.

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

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

The schema already documents applicationId thoroughly and input partially. The description adds the key semantic pointer: 'Call list_telegram_operations for the input schema' and warns that only documented fields are accepted. This compensates for much of the missing parameter context, though botId remains undocumented in both the schema and the description.

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

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

The description clearly states the action: 'Submit one supported read operation on the connected telegram_mtproto account.' It names the resource, the read-only nature, and the supported operation set via the schema enum. It also distinguishes itself from siblings by pointing to list_telegram_operations for input schema and get_telegram_operation for polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage instructions: call list_telegram_operations for the input schema, submit one operation, then poll get_telegram_operation until completed, error, or timed_out. It also states the required permission (manage_broadcasts) and account-level constraints, so an agent knows how and when to use the tool correctly.

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

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

Discloses read-only behavior (consistent with annotations), highlights performance impact ('heaviest read in the API'), and outlines workflow dependency (read before update). Adds significant value beyond annotations.

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

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

Three front-loaded sentences with no redundancy: purpose, usage guidance, and workflow advice. Every sentence serves a distinct purpose.

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

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

Given the read-only nature, annotations, and no output schema, the description fully covers what an agent needs: scope, performance hint, prerequisites, and relationship to sibling tools.

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

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

While schema coverage is 100%, the description adds valuable context: blockId is from get_flow_context, and applicationId has conditional default behavior with error handling guidance. This exceeds baseline 3.

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

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

The description specifies exactly what the tool returns ('block data, action configs, HTTP request bodies, custom-code files, triggers, menu payloads, and media paths') and distinguishes it from get_flow_context by advising use of the latter for exploration first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (read a known block) and when not to (use get_flow_context for exploration), warns it's the heaviest read, and advises reading before updating. Provides clear context for appropriate invocation.

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

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

Beyond annotations (readOnlyHint=true), the description adds important behavioral nuance: 'Sent counts reflect messages attempted, not confirmed deliveries.' This clarifies the meaning of the returned data.

Agents need to know what a tool does to the 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 plus a clarifying note) and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

For a read-only analytics tool with 4 well-documented parameters and no output schema, the description is fairly complete. It provides the key behavioral nuance and date window context, though it omits error conditions or pagination 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 100%, so the schema already documents all parameters. The description adds minimal extra meaning beyond referencing 'optional date window' for startDate/endDate. The baseline of 3 is appropriate.

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

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

The description clearly states it returns engagement analytics for a broadcast with delivery breakdown and per-message-block counts. It distinguishes from sibling tools like get_broadcast_details by specifying analytics and delivery breakdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 does not explicitly state when to use this tool versus alternatives. It implies usage for analytics over a date window but lacks 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?

Read-only is already in annotations, but description adds meaningful behavior: contact-variable values may contain personal data, and SECRET-type variables are always redacted. Also explains the return scope (full profile plus every contact-variable value), which is valuable given no output schema.

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

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

Two sentences, front-loaded with the core purpose. Each sentence adds unique value: return scope, read-only safety, redaction caution, and prerequisite step. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, description compensates by stating the return contents and redaction behavior. It also gives the prerequisite call. However, it doesn't detail profile fields or error cases, but with schema covering parameters and annotations marking read-only, it 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?

Schema has 100% coverage of both parameters, so baseline is 3. Description provides a practical pointer to list_contacts for contactId but does not add semantic detail beyond the schema's property 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?

Description uses specific verb 'Return' and specifies resource: one contact's full profile plus every contact-variable value. This distinguishes from sibling list_contacts (multiple contacts) and create/update_contact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructs to call list_contacts first to find contactId, giving clear prerequisite and usage context. It does not explicitly mention when not to use or compare to alternatives beyond list_contacts, so not a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces 'Read-only.' It adds many behaviors beyond annotations: ordering ('newest first'), capping and truncation ('Goals and clicks are capped separately by limit; goalsTruncated/clicksTruncated say when older events exist'), event scope ('typed replies, commands and website visits never appear'), error handling ('An unparsable value is rejected, never ignored'), and permission requirements ('Requires the view_logs permission'). This is rich behavioral context that goes well beyond the annotation metadata.

Agents need to know what a tool does to the 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 the sibling distinction, event scope, capping/truncation details, and a required prerequisite. No filler or repetition—each clause contributes to correct usage.

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

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

Despite lacking an output schema, the description conveys what the tool returns (goals, clicks, and optionally flowRuns) and how to interpret truncation flags. It covers prerequisites, error cases (MCP_APPLICATION_REQUIRED), permission requirements, and value formats. An agent has everything needed to call it correctly without further lookups.

Complex tools with many parameters or behaviors need more documentation. 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 parameters are already documented. The description adds meaning that the schema does not: it clarifies what 'clicks' means ('inline/menu button presses inside the bot'), explains the independent caps per stream tied to limit, and notes the permission requirement for includeFlowRuns. This adds valuable context beyond the schema's field descriptions, though it does not enumerate each parameter.

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

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

The description opens with the exact resource and action: 'Return one contact's engagement history: goals they achieved and buttons they clicked, newest first, plus all-time goal totals.' It explicitly distinguishes itself as the per-contact companion to get_broadcast_analytics (which is aggregate), making its purpose immediately clear and differentiating it from the obvious sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names the alternative (get_broadcast_analytics) and explains when to choose each: 'per-contact companion to get_broadcast_analytics (which is aggregate)'. It also provides a prerequisite: 'Call list_contacts first to find the contactId.' and clarifies the scope of what counts as clicks. This is explicit when-to-use guidance with exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description goes well beyond them: 'needs no API key', the stateful two-phase retrieval behavior (first call returns a compact index with one-line pointers, second call expands only the named sections), and the constraint that these rules are not enforced by validation.

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

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

Front-loaded with purpose and the no-arg index behavior before the two-call mechanics. Dense but nearly every clause carries information; the worked example object costs a little length but earns it by disambiguating the second-call shape.

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

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

With no output schema, the description carries the return-value burden and does so: it explains that a bare call returns a compact index and a parameterized call returns named sections in full. Combined with the usage protocol, an agent has everything needed to call it correctly in both modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it shows that calling with NO arguments yields the index, and it provides a concrete example object showing sections used to expand specific ids, plus the relationship between examples and sections ids.

Input schemas describe structure but not intent. Descriptions should explain 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 sentence states a specific verb+resource (return flow-design rules) and immediately scopes it: the rules validation does NOT enforce. It distinguishes itself from validate_actions by naming that sibling and explaining why this tool exists alongside it.

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

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

Explicitly says to read it before any structural edit (new blocks/branches/flows), prescribes the two-call pattern (bare call = index, second call names touched sections), and motivates it with the concrete failure mode 'a batch can pass validate_actions and still be badly structured'. When-to-use, how-to-use, and the alternative are all present.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only, computed on demand from the execution log.' It adds useful behavioral context beyond the annotation: the 30-day window, the on-demand computation model, and the exact set of metrics. It does not describe the exact output shape, but no output schema exists and the metric list is fairly complete.

Agents need to know what a tool does to the 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 clause earns its place: expected metrics, the differentiator from the funnel sibling, source of flow ids, and read-only/on-demand nature. It is front-loaded with the core purpose and has 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, the description covers the return semantics well by listing the measured quantities. It also handles parameter sourcing and the tool's read-only safety profile. Minor omissions like exact response formatting or pagination are not critical for this tool, but a fully explicit return structure would push it to 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by telling the agent to pass flow ids from get_workspace_summary or the flow index, which clarifies where to source the required parameter. The schema already handles the 1–5 limit, applicationId defaults, and error behavior, so the description is not overburdened.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource ('Measure how NAMED flows are actually used') and enumerates the concrete metrics returned (contacts entered, per-block stop rate, human-agent answers, errors). It also distinguishes itself from get_funnel_analytics, so an agent can tell the tools apart 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?

The description explicitly contrasts this tool with get_funnel_analytics, explaining that the funnel cannot see flows reached via menu buttons, sequences, or handoffs, and that this tool works for ANY flow. It also tells the agent where to get the flow ids (get_workspace_summary or the flow index), giving clear when-to-use and sourcing guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds 'needs no API key', which is useful behavioral context beyond annotations. It also discloses the optional action batch inclusion, but does not elaborate on potential size implications or rate limits, keeping it at a 4.

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

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

Three sentences with zero waste. The first sentence states the core function, the second adds safety and access notes, and the third gives actionable usage guidance. Purpose is front-loaded, making it easy to scan.

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

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

For a simple read operation with two parameters, the description covers purpose, usage flow, and behavioral traits. It references sibling tools appropriately, and given no output schema, the return type is implicitly understood. No gaps remain for selection or 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 covers both parameters fully (100% coverage). The description adds value by explaining the downstream purpose of 'includeSchemaExample' for adaptation into 'apply_actions', and clarifies the 'id' as returned by search_flow_examples, going beyond the schema's description.

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

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

The description uses the verb 'Return' and specifies the resource 'reusable flow example by id'. It clearly distinguishes itself from siblings by explicitly mentioning 'search_flow_examples' and 'apply_actions', providing context for its role in a workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructs to 'Call search_flow_examples first to find the id', guiding when to use this tool. It also explains the optional parameter's purpose relative to 'apply_actions', giving clear context for proper sequencing.

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 include readOnlyHint=true, and the description reinforces this with 'Read-only, computed on demand from the execution log'. It adds non-obvious semantics: dropoff is null when no stage is actionable, large stopped counts on the first block are normal, and absence of a flow means unmeasured rather than healthy. This goes well beyond annotations and prevents misinterpretation.

Agents need to know what a tool does to the 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 unique information: result contents, dropoff semantics and caveat, entry-flow exclusion, read-only provenance, and a recommendation guardrail. It is front-loaded with the main purpose and tightly edited with no filler.

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

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

There is no output schema, so the description compensates by enumerating the measured values (entries, blocks reached, stop rates, dead buttons, goal counts) and defining the dropoff field. It also covers data source, read-only nature, and action guidance. An agent can decide when to call it and interpret the result without needing additional 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 100%, and the schema fully documents applicationId: optional, key-scoped default behavior, failure mode MCP_APPLICATION_REQUIRED, and how to obtain the id via list_applications. The tool description adds no parameter-specific information beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Return'), resource ('measured conversion funnels of the workspace's ENTRY flows'), and time window ('last 30 days'). It also defines what counts as an entry flow and explicitly excludes menu-button, sequence, and operator-handoff flows, which differentiates it from related flow-analytics tools. 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?

Clearly scopes when to call it: only for entry flows that a person can start themselves, and it explicitly says flows reached from menu buttons, sequences, or operator handoffs are not measured here. It also gives a decision rule: propose nothing when funnels are healthy or too thin. It does not name an alternative tool explicitly, so the 'vs alternatives' guidance is strong but slightly implicit.

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

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

Annotations declare readOnlyHint=true, and the description reinforces 'Read-only'. It adds behavioral context: the tool returns a summary (not full details), and clarifies that input fields and setup requirements come from get_module_details. Also explains behavior for applicationId omission based on key type, which is beyond what annotations provide.

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

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

The description is compact, front-loading the core purpose, then providing usage guidance and behavioral notes in a logical order. Every sentence adds value without redundancy.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, usage context, behavioral traits, and parameter behavior. It does not need to explain return values (no output schema). Minor omission: no mention of pagination or limits, but the tool returns a 'compact index', implying it is not large.

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

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

Schema coverage is 100% with a clear description for applicationId. The description adds extra context about default behavior for app-scoped vs personal keys and the error if omitted. This adds value beyond the schema, though not extensive.

Input schemas describe structure but not intent. Descriptions should explain 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 returns a compact index of modules with specific fields (key, versions, description, actions, triggers). It distinguishes itself from siblings by positioning as the starting point for marketplace capabilities, then directing to get_module_details and install_module for further 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?

Explicitly tells when to use the tool: 'Start here when you need a capability the core action kinds do not cover'. Also provides clear next steps: call get_module_details for input fields and install_module to add a module. The note about return type (summary only) further guides usage.

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

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

Annotations already declare readOnlyHint=true, and the description adds detailed behavioral context: what data is returned (action input fields, trigger config, setup fields, references to installed actions), error handling for unknown moduleKey, and the fact that it is read-only. No contradictions with annotations.

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

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

The description is concise at four sentences, front-loaded with the main purpose. Each sentence adds value: main functionality, read-only hint, workflow steps, and error behavior. No redundant or unnecessary 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?

The description provides a high-level overview of the return data (action input fields, trigger config, setup fields, references to installed actions) and error handling. With no output schema, this is reasonably complete, though a more detailed breakdown of the success response structure would improve completeness.

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

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

Schema coverage is 100%, so all three parameters already have clear descriptions in the schema. The description does not add significant additional semantics beyond those descriptions; it only provides workflow context. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states that the tool returns 'everything needed to use one module' including action input fields, trigger configuration, manual setup fields, and references to installed actions. It distinguishes itself from siblings like get_module_catalog (which returns a list of modules) and install_module, and explicitly advises calling get_module_catalog first and calling this tool again after install_module.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance: 'Call get_module_catalog first to obtain moduleKey' and 'call this again after install_module to read the installed action references.' It also explains the behavior when moduleKey is unknown (returns error with availableModules) and when to omit moduleVersion (to resolve installed version). No ambiguous or missing guidance.

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

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

Annotations already mark readOnlyHint=true; the description adds meaningful behavioral details beyond that: 'computed on demand over the last 30 days', 'Counts are DISTINCT contacts', and the explicit 'Read-only' statement. It also notes failure conditions indirectly via schema parameter descriptions, though not repeated in the description. This is richer than minimal and earns a 4.

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

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

The description is lengthy but every sentence contributes: it states purpose, explains the survey concept, describes both invocation modes, and justifies the tool's advantage over dropoff analytics. The structure is front-loaded with a clear purpose, though the 'stronger than dropoff' sentence could be trimmed without losing essential guidance.

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

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

There is no output schema, so the description must cover return expectations. It does so for both modes (summary counts for listing, per-question shares and text answers for detail) and notes the time-window default. The splitGoalKey parameter is only documented in the schema, not the description, but that's covered well enough by the schema. Overall, the description is adequate for correct invocation without being exhaustive.

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

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

Input schema coverage is 100% with good parameter descriptions. The tool description adds extra semantic value by explaining the two calling modes for flowId (listing vs. detail) and the default time window for days, which is not fully captured in the schema alone. This exceeds 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 opens with a specific verb and resource ('Read what customers ANSWERED in this workspace's surveys') and clearly distinguishes two modes: listing all surveys vs. retrieving per-question results for one flow. It also contrasts itself with dropoff analytics, stating this tool provides stronger, stated reasons, which differentiates it from analytics siblings.

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

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

The description explicitly explains when to call without flowId (to list surveys) and when to pass flowId (to get per-question results), and it argues why this tool is preferable to dropoff rates. It stops short of naming a specific sibling tool or listing exclusions, so it's not a full 5, but it provides clear contextual guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses substantial runtime behavior: the manage_broadcasts permission requirement, one-hour result expiry, 60-second timed_out semantics, offline/restarted-runtime implications, and throttling retry rules. This gives the agent the full lifecycle picture of an async operation. There is no contradiction with the annotations (readOnlyHint=true is consistent with 'Read').

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

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

Five tightly packed sentences, each earning its place: purpose, permission, polling cadence, expiry, timeout behavior, and retry handling. No filler or repetition of schema content, and the core purpose is front-loaded.

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

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

Despite having no output schema, the description covers the essential operational envelope: what it reads, how to poll, result expiration, timeout meaning, and error retry handling. It references key result fields (timed_out, error.retryAfterSeconds). The only gap is that the full return shape is never described, which matters more because no output schema exists.

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

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

Schema coverage is only 33% (only applicationId is documented), so the description must compensate. It does address the highest-risk semantic: requestId, botId, and applicationId must be the same ones used at submission, and it references requestId as the operation identifier. However, botId's format and purpose remain under-specified beyond the matching constraint, so compensation is strong but not complete.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Read a Telegram operation status and result' — clearly a read/scoping action distinct from create/list siblings. It names the identifying key (requestId) and scoping constraint (same applicationId/botId as submission), so an agent can distinguish it from execute_telegram_operation (submission) and list_telegram_operations (bulk query) without opening their 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?

The description gives strong operational context: poll every two seconds, results expire after one hour, timed_out means no result within 60 seconds and a new request is needed, and throttling errors require honoring error.retryAfterSeconds. This effectively documents the polling workflow around execute_telegram_operation. However, it never explicitly names an alternative tool or states a when-not-to-use condition, leaving the sibling differentiation implicit rather than explicit.

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

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

Description adds detailed behavior beyond annotations: pagination detection, conditional value inclusion, secret redaction, and default for includeValues. Annotations only state readOnlyHint=true, so this is essential.

Agents need to know what a tool does to the 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, each serving a distinct purpose: introduction, read-only declaration, return shape and pagination, value behavior and usage. No redundancy, well 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?

No output schema, so description covers return shape and pagination logic. Explains secret handling and default for includeValues. Could mention id format more, but agent can infer from usage instruction. Adequate for correct tool use.

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

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

Schema coverage is 100%, so baseline 3. Description adds value for some parameters: mentions default/clamping for limit, suggests calling list_applications for applicationId, explains 500-char preview for includeValues. Not all parameters get extra context, but enough to improve 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?

Clear verb 'search' and resource 'variable definitions' with explicit scope (by scope and keyword). Distinguishes from sibling tools like get_flow_context and get_application_context by focusing on variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on interpreting pagination (compare returned vs total), handling value redaction, and using ids in references. Lacks explicit when-not-to-use or alternative tools, but context is sufficient for correct invocation.

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

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

Beyond the readOnlyHint annotation, the description reveals the polling behavior, the terminal status values, and the kind of data returned (counters, warnings, unimported pages). This adds meaningful behavioral context that the annotation alone does not provide.

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

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

The description is a single dense sentence that packs the resource, return contents, read-only nature, and polling guidance without wasted words. It is front-loaded with the most important identity information first.

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

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

Given the tool's simplicity, the absence of an output schema, and the two well-documented parameters, the description covers everything an agent needs: what the tool returns, when to poll, and when to stop polling. No critical behavioral or return-value information is missing.

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

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

Schema description coverage is 100%, so the schema already documents jobId and applicationId sufficiently. The description adds contextual framing about import status but does not add new parameter-level meaning beyond what the schema provides.

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

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

The description clearly specifies that this tool retrieves the status of a website import, naming the exact fields returned (stage, progress, counters, warnings, unimported pages) and the actions that initiate the import. This distinguishes it from sibling import_website_knowledge, which starts an import rather than reporting its status.

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

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

The description gives clear operational guidance: poll this tool until status reaches DONE, DONE_WITH_ERRORS, or FAILED. It also identifies the context in which the tool applies by referencing the two import actions, but it does not explicitly state when not to use it or mention alternative tools by name.

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

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

The description restates the read-only nature, which matches the annotation, and adds a behavioral detail about the omission of certain data. It also notes a specific error condition for personal keys when applicationId is omitted (MCP_APPLICATION_REQUIRED), which is useful context not captured in annotations. The description does not contradict 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 three sentences, each adding value without redundancy. The first sentence states the purpose, the second confirms safety, and the third provides usage boundaries with alternatives. 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?

Despite lacking an output schema, the description sufficiently characterizes the return content (compact summary of entities) and clearly explains parameter behavior and error conditions. With two optional parameters and full schema coverage, the description completes the picture 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 coverage is 100%, yet the description adds significant meaning: for flowId it clarifies that omitting it summarizes all flows; for applicationId it explains default behavior and error handling, and suggests calling list_applications. This goes well beyond the basic schema 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 that the tool returns a compact summary of application, flow, sequence, operation, and bot details, and labels it as the cheapest way to orient in a workspace. It distinguishes itself from sibling tools by explicitly listing what it omits (variables, full flow graphs) and directing to alternatives, making the purpose unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, italicizing the omitted features and naming specific sibling tools (get_variable_context, get_flow_context, get_application_context) for more detailed needs. This directly informs the agent about appropriate invocation contexts.

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

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

The annotations only signal that the operation is not read-only, while the description discloses substantial behavior beyond them: robots.txt handling, junk/duplicate filtering, default blog inclusion, maxPages cap, async job semantics, and host-based default naming. This gives an agent an accurate model of side effects and lifecycle.

Agents need to know what a tool does to the 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 each sentence earns its place: purpose, base creation behavior, crawl filters, async return, and a usage guardrail. There is no filler or unnecessary 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 7-parameter tool with no output schema, the description covers the important non-obvious aspects: new-vs-existing base behavior, asynchronous job polling via get_website_import, crawl filtering policies, and a guardrail about not writing facts from unread sites. This is sufficient for an agent to invoke it correctly and know what to do next.

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

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

Schema coverage is 100% and the schema descriptions are already highly detailed, including defaults, optionality, failure modes, and URL path scoping. The description adds context like default naming and crawl filtering, but it does not need to restate the schema in full; baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Crawl a website into a knowledge base', and explains the intended downstream use for an AI_TOOL_ROUTER. It also differentiates the tool from get_website_import by clarifying that this starts the import and returns a job to poll.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: use this to ingest a website that has not been read, and use get_website_import to poll the resulting job. The 'Prefer this over writing facts about a site you have not read' is a helpful when-to-use rule, though it does not spell out broader exclusion cases such as when to reuse versus create a base beyond the knowledgeBaseId parameter.

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?

Disclosure goes beyond annotations: explains idempotency (re-running does not duplicate), mentions manual setup needs, and warns about credential requirements. Annotations already hint at idempotency, but the description adds vital behavioral details.

Agents need to know what a tool does to the 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 with logical flow: purpose, permission, workflow, idempotency, and post-install concerns. Slightly verbose but each sentence earns its place. Could tighten 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?

Covers prerequisites, workflow, idempotency, and follow-up steps. Lacks error scenarios (e.g., invalid moduleKey), but overall adequate for a 3-param tool with no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value: links moduleKey to get_module_catalog, explains applicationId default logic (app_ vs usr_ keys), and stresses that moduleVersion must be exact with no implicit latest.

Input schemas describe structure but not intent. Descriptions should explain 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 installs an exact module version and creates missing template actions. It distinguishes from sibling tools like get_module_catalog (selection) and get_module_details (post-install inspection) by mentioning them in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 required permission (manage_automation), recommends calling get_module_catalog first and get_module_details after, and notes idempotency and manual setup fields. This provides comprehensive when-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?

Annotations already declare readOnlyHint=true. The description adds beyond this by specifying the return format (array of {id, name, role, permissions}) and the meaning of an empty array (valid key but no application). No contradictions.

Agents need to know what a tool does to the 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 concise sentences, front-loaded with purpose and immediate usage guidance. 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?

For a zero-parameter read-only tool with no output schema, the description fully covers purpose, usage context, return structure, and edge cases (empty array). No 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?

No parameters exist (schema coverage 100%), so baseline 4 applies. The description correctly notes 'takes no arguments', adding no further semantic value 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 description clearly states the verb 'List', the resource 'applications', and the scope (accessible by this API key). It also distinguishes this tool as the starting point for personal API keys, differentiating it from siblings that require an applicationId.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Start here when using a personal API key (usr_...): every other tool needs an explicit applicationId, which this tool supplies.' Provides clear context for usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' is consistent with them. Beyond annotations, it discloses filter combination semantics (AND), tag union behavior, total-count semantics for cheap counting, compact return shape, and the platformId-per-bot data model quirk. No contradiction with annotations.

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

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

Five dense sentences, each earning its place: purpose/ordering, safety, filter semantics with tag guidance, counting trick, and return-shape routing plus a data-model caveat. The most important facts are front-loaded and there is no repetition of schema content.

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

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

For a 9-parameter tool with no output schema, the description covers every decision point: scope, ordering, filter composition, search fields, tag naming convention, return semantics, and sibling routing. The compact-summary and total notes partially compensate for the missing output schema. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-cutting meaning the schema does not convey: filters combine as AND, search matches the listed fields, tags/tagIds form a union, and platformId is unique only per bot. This is genuine value beyond the per-parameter schema descriptions, though it deliberately does not re-describe each parameter.

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

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

Opens with a specific verb+resource: 'List and search contacts in the application, paginated, newest first.' It names scope, ordering, and pagination, which distinguishes it from get_contact (single contact), list_contact_tags (tags only), and the create/update contact mutations. The 'Read-only' qualifier further separates it from mutation siblings.

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

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

Provides explicit routing to alternatives: 'use get_contact for one contact's variables' and 'discover them with list_contact_tags' for UTM tag names. The 'limit: 1 counts an audience cheaply' tip gives concrete when-to-use guidance, and the platformId-per-bot caveat tells agents when results will differ from their expectations. Clear context with named siblings.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds valuable behavioral detail: tags appear only if attached to at least one contact in scope, results are ordered most-used first, and UTM tag semantics are explained. It repeats 'Read-only' but also contributes behavior 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 concise and well-structured: it front-loads the core purpose, then provides relevant attribution context, then gives a practical pointer to list_contacts. Every sentence earns its place and there is no filler or redundant detail beyond the minor 'Read-only' 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 read-only listing tool with four optional parameters and no output schema, the description is complete. It explains the scope, ordering, inclusion criteria, attribution meaning, and how to continue into list_contacts. Nothing essential is missing for an agent to select and 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 100%, so the schema already documents all four parameters, including the applicationId behavior with MCP_APPLICATION_REQUIRED. The description adds helpful examples for the search parameter ('utm:' and '_0905') and relates tag names to list_contacts, but it does not substantially expand parameter meaning 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 description states a specific verb and resource: 'List the contact tags in use in the application (or one bot) with how many contacts carry each, most-used first.' It clearly distinguishes this from sibling tools by framing it as the attribution view and explicitly referencing list_contacts for the next step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context: this is for viewing tag counts and UTM attribution, and it explicitly says to pass a tag name to list_contacts to page through or count contacts. It implies 'use this for tag summaries, list_contacts for contacts,' though it does not explicitly state when not 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?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds useful behavioral context beyond the annotation: defaulting to open items, ordering by severity then due time in dashboard order, carrying measured evidence, and clarifying that counted conversations/log rows are not moved or deleted.

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

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

The description is dense but every sentence earns its place: purpose, item kinds, read-only nature, default ordering, evidence semantics, and sibling routing. It is front-loaded with the core purpose and does not waste words.

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

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

For a read-only list tool with nine parameters and no output schema, this description covers the essential context: what items are, how they are ordered, what they contain, how to access related data, and when to use sibling tools. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by giving concrete examples of attention items ('failing flows, a failed broadcast, an unsubscribe spike') and clarifying the queue's ordering semantics. This enriches parameter understanding even though most parameter-level detail already lives in the schema.

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

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

The description opens with a specific verb and resource: 'List Pulse items — the workspace attention queue.' It clearly distinguishes the two item kinds and explicitly points to get_pulse_item and update_pulse_item as alternatives, so an agent can tell exactly what this tool does and how it differs from siblings.

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

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

The description explicitly says when to use alternatives: 'Use get_pulse_item for one item's full evidence and proposed change, and update_pulse_item to close one.' It also explains that referenced conversations and log rows stay in place and are reachable with read_messages and query_flow_logs, giving clear routing guidance.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: it requires manage_broadcasts, operates only on public data, and does not connect to Telegram. It also clarifies botId fallback behavior. No contradiction with annotations exists.

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

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

Three dense sentences each add value: what the tool returns, the required permission and safety profile, and an important optional-parameter rule. There is no redundancy 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 read-only catalog tool with no output schema, the description is complete: it states the purpose, return contents, permission requirement, side-effect-free behavior, and parameter caveat. An agent has enough information to invoke it correctly and interpret its role among the sibling tools.

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

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

The schema only documents applicationId, leaving botId entirely undocumented. The description compensates by explaining botId may be omitted when the application has exactly one userbot, which adds real behavioral meaning 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 description states a specific action (Discover) and resource (supported Telegram MTProto account operations), and names the kind of information returned (input schemas, permissions, limits). It clearly distinguishes this listing tool from execution tools like execute_telegram_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 description provides useful context such as requiring manage_broadcasts and noting that the catalog does not connect to Telegram, which implies it is a safe discovery step. However, it does not explicitly say when to use this tool instead of get_telegram_operation or execute_telegram_operation, or mention any 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?

Adds behavioral traits beyond annotations: fail-closed (unlisted messages dropped), contacts never materialize, DMs always pass. The readOnlyHint annotation is reinforced but the description goes further with the source-of-truth semantics.

Agents need to know what a tool does to the 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 – purpose, behavioral context, botId usage. 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?

Well-rounded despite no output schema; explains the impact of the watched list and when botId can be omitted. Could mention return format, but given simplicity and annotations, it's nearly 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 already covers both parameters with descriptions (100% coverage). The description's botId note repeats the schema. No new parameter-level insight.

Input schemas describe structure but not intent. Descriptions should explain 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 'List the group/channel chats a telegram_mtproto userbot monitors' – a specific verb+resource. 'Read-only' distinguishes it from set_watched_groups sibling. Clear 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?

Explains the watched list as source of truth, fail-closed behavior for unlisted chats, and DMs always pass. This gives an agent context for when to query the list. Does not explicitly name alternatives but implies the read counterpart to set_watched_groups.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes further by disclosing the required view_logs permission, the groupBy mode split and its row/group semantics, and the bounded window (default 24h, max 30 days). These are behavioral facts not present in 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?

Front-loaded with the resource identity and safety, then modes, then constraints, then the alternative — a logical order with little waste. It is dense and long, but each sentence carries distinct operational value for a 12-parameter tool, so the length is justified rather than padded.

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

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

For a 12-param, zero-required read tool with no output schema, the description supplies what the structured fields cannot: the mode model, the window bounds, auth requirement, and the sibling alternative. An agent has enough to select and invoke it correctly without opening the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nonetheless adds meaning beyond the schema by explaining what groupBy values signify (error=distinct failures, action=which step, flow=where, day=whether new) and how mode selection changes output shape, which the schema does not convey.

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

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

States a specific verb and resource (read the bot execution log / flow_execution_log) and adds a discriminating qualifier: it is the only place separating 'the action ran' from 'the action produced output'. It also explicitly names the narrower sibling read (get_contact_activity with includeFlowRuns), so an agent can route between them.

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

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

Gives explicit when-to-use guidance for the two modes: without groupBy returns newest rows, with groupBy returns a rollup for 'what is failing right now'. It even recommends a concrete dimension mapping (error, action, flow, day) and prescribes the follow-up workflow (re-run with same filters and no groupBy). Alternative for a single contact is named with its condition.

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

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

Beyond the readOnlyHint annotation, the description discloses the ledger source, recording-before-routing behavior, inclusion of unmatched messages, text-only/caption behavior, redaction after the retention window, pagination via nextCursor, and the required view_logs permission. This is rich behavioral context that annotations alone do not provide, and it does not contradict the annotations.

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

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

The purpose is front-loaded in the first sentence, followed by logically ordered details about source, filtering, pagination, exclusions, retention, and permissions. Every sentence carries distinct information with no filler, and the structure makes the long description easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 9 parameters with none required, the description is exceptionally complete: it covers ordering, filtering dimensions, pagination, data retention redaction, text-only behavior, permission requirements, and the boundary with get_contact_activity. An agent has enough context to decide when to use it and what to expect from the response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the input schema already says about filters like contactId, botId, direction, actor_type, startDate/endDate, and cursor. It adds a small amount of conceptual clarity (e.g., actor_type distinguishes human agent replies) but does not materially extend the parameter documentation already present in the schema.

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

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

The description opens with a specific verb and resource: 'Read the message transcript' and gives precise scope: 'what users sent the bot and what the bot sent back, newest first.' It also distinguishes itself from a sibling by noting that button taps are not messages and never appear here, making the tool's role 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 gives explicit usage boundaries: button taps should be handled by get_contact_activity, and actor_type is called out as the way to find conversations automation did not finish. It also includes contextual guidance such as unmatched messages being present and the retention-window redaction behavior, so an agent knows what results to expect.

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

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

The description goes well beyond the annotations. It discloses the required permission, details the partial-update (idempotent) behavior, explains variable-name resolution and failure with 422 before writing, states that variable writes propagate to the live bot immediately, and describes the side effect of setting status to 'unsubscribed' (stops broadcasts and sequences). This is rich, actionable 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?

The description is five sentences, each serving a distinct purpose: main action, permission, idempotency, variable semantics, and side-effects. It is front-loaded with the core purpose and contains no filler or redundant phrasing.

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

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

Despite having no output schema, the description covers all critical operational aspects: permission requirements, partial update semantics, error behavior, propagation timing, and side effects on broadcasts/sequences. Given the tool's complexity (9 parameters, nested object, enums), this level of detail is excellent and leaves no major gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining that the variables map takes names (or folder paths) and that unknown names fail with 422 before any write. It also clarifies the partial-update semantics for all fields, which is not fully captured in the schema's 'Omit to leave unchanged' notes. This pushes it above baseline.

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

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

The description opens with a specific verb+resource: "Update a contact's profile fields and/or contact-variable values." This clearly distinguishes the tool from siblings like create_contact, get_contact, and list_contacts by conveying that it modifies existing contacts and their variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context for when to use the tool: it requires the manage_broadcasts permission, and it explains partial-update semantics. It does not explicitly name alternatives or warn against using it for creation, but the sibling list and the verb 'update' make the use case unambiguous. The omission of explicit exclusion is a minor gap.

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

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

The annotations already mark this as a mutating, idempotent, non-destructive tool. The description adds valuable behavioral detail beyond that: completing does not message the contact, and snoozing also moves the due time so the task reappears afterward. It does not describe reopen/reschedule side effects, which keeps it from a 5.

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

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

Three dense sentences with no filler. The action list is front-loaded, and the second and third sentences each add a distinct behavioral clarification that 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 7-parameter tool with 100% schema coverage, the description plus schema is sufficient for correct invocation. The main missing piece is the lack of any mention of return values or response shape, especially since there is no output schema.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the schema. The description adds a small amount of related context about snoozing affecting due time, but it does not meaningfully expand on individual parameter semantics.

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

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

The description names the exact resource ('one follow-up task') and all supported actions: close, reopen, snooze, or reschedule. It also clarifies what completing means ('records that a person handled the reminder'), which distinguishes it from messaging 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 clear context for when to use this tool and explicitly notes that it does not message the contact, preventing use as a send_message alternative. It does not name sibling tools like create_follow_up_task or list_follow_up_tasks explicitly, so it falls just short of a 5.

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

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

Even with readOnlyHint=true in annotations, the description adds meaningful behavioral detail beyond the annotation: it is safe to repeat, returns the same errors/warnings as apply_actions, and passing validation does not mean the design is sound. It also discloses that apply_actions execution is non-atomic flagging state-re-read needs.

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

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

Every sentence earns its place: the dry-run behavior is front-loaded, followed by the redundancy warning, the return-value equivalence, and the design-soundness caveat. The wording is compact, direct, 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?

There is no output schema, but the description says the tool returns the same errors and warnings apply_actions would report. Combined with rich parameter schemas covering placeholders, defaults, and application-id handling, and the explicit limitation about design guidelines, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no new parameter-level meaning; however, the schema already documents flowId defaults, applicationId scoping and MCP_APPLICATION_REQUIRED failure, action placeholders, and the non-atomic retry caveat.

Input schemas describe structure but not intent. Descriptions should explain 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 'Dry-run validation of a proposed batch of flow-builder actions,' which names a specific verb, resource, and scope. It also contrasts with apply_actions by stating it mutates nothing, so the tool's role is unambiguous even among many siblings.

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

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

The description explicitly says apply_actions already runs this exact validation and applies nothing when invalid, so calling validate_actions first is redundant. It then states the only intended use case: checking a draft you do not intend to apply yet. This is precise 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.