FlowCastle

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

Even though annotations already declare destructiveHint=true and idempotentHint=false, the description adds substantial context: which entities delete_operation and delete_broadcast additionally destroy (hidden graph flow, run history, delivery history), that run_operation has irreversible external side effects and is not idempotent, that execution is NOT atomic despite validation being all-or-nothing, and that applying does not publish until deploy_application runs.

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 (~250 words), but for a 28-action write path the length is largely justified and it is front-loaded: purpose, then when-to-use, then destructive/irreversible warnings, then return and publishing behavior. A few clauses could be tightened, 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?

Given the tool's complexity and the absence of an output schema, the description is thorough: it covers return shape ({ success, changes, errors, warnings, actionId } plus idRemap), non-atomicity and retry guidance, deletion consequences, and the draft-vs-published distinction with the deploy step.

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 flowId, actions, target, validation, and applicationId in detail. The description adds batch-level semantics (array order, placeholder idRemap) but little parameter-specific detail beyond what the schema carries, so baseline 3 applies.

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

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

The opening sentence gives a specific verb+resource ('Validate and apply a batch of flow-builder actions') and scope ('the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders'). It explicitly distinguishes itself from validate_actions, which an agent could otherwise confuse it with.

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

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

Gives explicit when-to-use guidance ('Call this directly; a separate validate_actions call beforehand is unnecessary'), names the alternative (validate_actions) and the reason to skip it, and routes broadcast work here with the create_broadcast/update_broadcast recipe. It also states the confirm-with-user condition before deletions and run_operation.

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

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

Annotations already indicate non-idempotent (idempotentHint=false) and non-read-only (readOnlyHint=false). The description goes beyond by explaining the exact consequences: seeds default flows unless skipped, creates persistent state, and is not idempotent. It also details the authentication requirement (personal API key). No contradiction with annotations.

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

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

The description is four sentences, front-loading the core purpose. Each sentence adds distinct information: purpose, auth restriction, default behavior, idempotency, and return value. No redundant or extraneous text.

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

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

Given no output schema, the description explains the return value (new application id) and its usage in other tools. It covers all three parameters with sufficient detail, the auth prerequisite, and behavioral aspects. The tool is simple, and the description fully equips an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining edge cases: name defaults to a localized string, skipDefaultFlows effect, and preferredLanguage silently falls back to 'en' for unsupported values. These details go beyond the schema descriptions, justifying a score 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 clearly states 'Create a new application (workspace) owned by the caller.' It specifies the verb (create), resource (application/workspace), and ownership. It implicitly distinguishes from sibling tools like update_application and list_applications by noting that the returned applicationId is used by other tools, making the creation role clear.

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

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

The description explicitly states when to use (to create an application), when not to use ('application-scoped keys cannot create applications'), and provides context on idempotency ('NOT idempotent'). It also gives guidance on optional behavior via skipDefaultFlows, making it clear when to include or exclude it.

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

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

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

Description discloses important non-obvious behavior beyond the annotations: creating persistent state, non-idempotence (two calls create two reminders), no message being sent on due date, and key-based assignment semantics. Annotations already include idempotentHint=false, but the description adds rich context about side effects and ownership.

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, non-idempotence, safety against misusing it as an automation, and key/ownership nuance. The most critical usage constraint 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?

For a side-effect-creating tool with no output schema, the description covers everything needed to invoke it correctly: what it does, that it is not idempotent, that it does not send messages, and how application/personal keys affect the created resource. No substantial gap remains.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds value by explaining assignment consequences of personal vs workspace API keys, which is not fully captured in the schema, and reinforces the optional contactId behavior for standalone reminders.

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 states a specific action on a specific resource: create a follow-up reminder for a person to reach back out to a contact. It also distinguishes itself from siblings like send_message, list_follow_up_tasks, and update_follow_up_task by framing this as a persistent to-do, not an automation.

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

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

Explicitly tells the agent when to use this tool vs alternatives: it is a to-do, not an automation, and the agent should use send_message or a broadcast to actually message someone. It also explains the API-key/application scoping behavior, which helps decide when this tool is appropriate.

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?

Beyond the readOnlyHint annotation, the description adds meaningful behavioral detail: it needs no API key, supports a two-step call pattern, returns an index with no arguments, and returns full contracts only for requested items. It also warns that the entire document is too large to read at once, which helps the agent avoid a problematic invocation strategy.

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

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

The description is front-loaded with the core purpose, then progressively explains the index-first workflow and filtering guidance. Every sentence contributes necessary behavioral or usage information, and the inline example is compact and illustrative without being 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?

Even without an output schema, the description adequately explains what will be returned in both invocation modes: the index contents, full contracts, batch contract, placeholder rules, and invariants. This gives an agent enough understanding to call the tool correctly and interpret its 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying that the parameters are selectors derived from the index and by giving a concrete example ({ blockTypes: ['AI_TOOL_ROUTER'], topics: ['knowledgeBases'] }) showing how to scope the request.

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

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

The description opens with a specific verb and resource: 'Return the action-authoring contract that apply_actions batches are validated against.' It clearly identifies the tool's output and distinguishes it from apply_actions and validate_actions by framing it as the source of the validation contract.

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 usage context: call with no arguments for an index, then call again with only the items the bot needs. It does not explicitly name sibling alternatives or say when not to use this tool, but the intended workflow is clear enough for an agent to select it appropriately.

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

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

Annotations already indicate readOnlyHint=true. The description adds context about returned data (flows, bots, variables, sequences, operations) and a specific note about hidden flow behavior, adding 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 focused sentences: purpose, usage guidance, and a behavioral note. No fluff, well-structured.

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 single parameter with full schema coverage and no output schema, the description adequately explains what is returned and differentiates from siblings. Could mention response size, but already covered indirectly.

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 fully covers the one parameter with clear description. The tool description adds no additional parameter semantics, so baseline is appropriate.

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

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

The description clearly states the tool returns the full application-level automation context, listing specific components (flows, bots, variables, etc.), and distinguishes it from a sibling tool (get_workspace_summary).

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 advises to prefer get_workspace_summary for simple name/count needs, providing clear when-to-use guidance and an alternative.

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

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

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?

Annotations already declare readOnlyHint=true, and the description repeats 'Read-only'. It adds value by listing the exact fields returned and implies no side effects. No contradictions. Slight additional context 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?

The description is three sentences long, front-loaded with purpose, and every sentence adds value: returns fields, read-only, prerequisite, alternative. No wasted 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?

Given no output schema, the description sufficiently explains return values (status, schedule, recurrence rule, linked flow, delivery breakdown). It also covers prerequisites and alternatives, making it complete for a simple read-only tool.

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

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

The input schema has 100% description coverage, so the schema already fully explains both parameters. The description does not add new parameter semantics beyond what the schema provides, meeting the baseline for coverage but not exceeding it.

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

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

The description clearly states the tool returns full details for a single broadcast, listing specific fields like status, schedule, recurrence rule, linked flow, and delivery breakdown. It distinguishes itself from the sibling get_broadcast_analytics by specifying its focus on status and delivery breakdown vs. engagement stats.

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 list_broadcasts first to find the broadcastId, and directs users to get_broadcast_analytics for per-message-block engagement stats. This provides clear when-to-use and when-not-to-use guidance with specific alternatives.

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

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

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 declare readOnlyHint=true, and the description adds 'Read-only, takes no arguments, and needs no API key' which is consistent. It also describes the content type and purpose, providing behavioral context 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?

The description is two sentences, front-loaded with the purpose, and every sentence adds value. No wasted 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 tool with no parameters and no output schema, the description adequately explains what is returned and why it is needed. It could mention the format, but that is minor.

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, and schema coverage is 100%. Baseline score for 0 parameters is 4, and the description correctly notes 'takes no arguments'.

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 'flow-design rules that validation does NOT enforce' with specific examples like splitting branches and wiring navigation. The verb 'Return' and resource 'flow-design rules' are precise, and it distinguishes itself from validation 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 explicitly advises to 'Read this before any structural edit' and explains why (rules catch issues validation misses). It lacks explicit when-not-to-use or alternatives, but the guidance is strong and context-specific.

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, but the description adds value by explaining what is deliberately omitted (block data, action configs) and why (to stay cheap). It provides behavioral context beyond the structured annotations.

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

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

Four sentences with zero waste: purpose, read-only, omission details with sibling reference, and usage guidance. All sentences earn their place; critical information is front-loaded.

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

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

For a tool that returns flow topology with no output schema, the description adequately describes what is returned (blocks, links, summaries) and what is not. It integrates well with sibling tools and provides complete context for an agent to decide when to call it.

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

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

Schema coverage is 100%, but description adds significant meaning for flowId (source functions) and applicationId (key type behavior, error condition, and how to get the id). This goes well beyond the 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 the tool returns 'one flow's graph topology: its blocks, how they link, and a short summary per block', with a specific verb (Return) and resource (flow topology). It distinguishes from siblings like get_block_details which returns full block contents.

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 'This is the normal first step before editing an existing flow' and contrasts with get_block_details for when block data is needed. No alternatives are ambiguous; it provides clear when-to-use and when-not-to-use context.

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

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

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 declare readOnlyHint=true, and the description reinforces that while adding meaningful context: the item includes underlying evidence and ids, and automatic resolutionPolicy items close themselves and cannot be closed by hand. 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?

Three short sentences front-load the main purpose, then add the prerequisite and a domain caveat. Every sentence contributes distinct information, and there is no filler.

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

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

For a simple two-parameter read tool with no output schema, the description explains what the response contains, notes the list_pulse_items prerequisite, and flags the resolutionPolicy behavior that could affect downstream decisions. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema fully documents itemId and applicationId, including the MCP_APPLICATION_REQUIRED failure mode. The description only restates the itemId source ('as returned by list_pulse_items') without adding parameter detail beyond the schema, so baseline 3 applies.

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

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

Description opens with a specific verb-resource pair ('Return one Pulse item in full') and enumerates the content: measured evidence, conversation and execution-log ids, and the change Apply would build. This clearly distinguishes it from list_pulse_items and update_pulse_item.

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

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

It explicitly states the prerequisite 'Call list_pulse_items first to get the itemId' and labels the operation as read-only. It does not name an alternative tool or state when not to use it, but the 'one item in full' framing and read-only marker provide clear usage context.

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

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

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 provide readOnlyHint=true, and the description redundantly states 'Read-only.' However, it adds valuable behavioral nuances beyond annotations: 'delivery counts report messages attempted, not confirmed deliveries' and 'Filters combine as AND.' This enriches the agent's understanding of output semantics and filtering behavior.

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

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

The description is compact and front-loaded with the core purpose, then adds necessary caveats and alternative-tool pointers. Each sentence serves a distinct function; even the redundant 'Read-only' is a single short word after the primary purpose. 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?

For a list tool with no output schema, the description conveys the expected response shape ('status, schedule, and delivery counts') and warns about delivery-count semantics. It does not detail pagination structure, but the schema's limit/page parameters and high overall coverage make this acceptable. The cross-references to related tools make it complete for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the crucial interaction 'Filters combine as AND,' which is not explicitly present in any single parameter description. It also clarifies that delivery counts refer to attempts, helping interpret parameters like status. This exceeds 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 states a specific verb and resource: 'List broadcasts in the application with status, schedule, and delivery counts.' It also distinguishes from sibling tools by directing users to get_broadcast_details for a single broadcast's full breakdown, making it clear what this tool does not do.

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

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

Provides explicit when-to-use guidance: lists broadcasts with filters combined as AND, and clearly names alternatives: 'Use get_broadcast_details for one broadcast's full breakdown' and 'To CREATE or SEND a broadcast use apply_actions... see get_action_schema under broadcasts.' This gives the agent a clear decision tree.

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, so the description's 'Read-only' is redundant, but it adds valuable beyond-annotation traits: 'Runs as SQL over the event tables, so it is safe on large workspaces' (performance/scalability), pagination behavior ('paginated, ordered by each contact's most recent matching event'), and the failure mode when goalKey is omitted ('fails with the list of known goal keys'). It does not disclose all potential error modes (e.g., missing blockId for BLOCK_SENT), but the goalKey discovery side effect is a strong behavioral detail.

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

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

The description is a compact single paragraph of four sentences, each earning its place: definition, kind enumeration, behavioral traits, and a performance/alternative note. It is front-loaded with the purpose ('The reverse lookup') and uses parallel structure for the event kinds, making it easy to parse without wasted 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?

Given the complexity (13 parameters, 1 required, conditional requirements) and no output schema, the description covers the core invocation logic comprehensively, including all four event kinds and their parameter dependencies. However, it does not describe the return shape of the contacts (e.g., whether full contact objects or just IDs are returned), which is a gap given the absence of an output schema. Otherwise, it includes ordering, pagination, and the performance rationale, making it quite complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics by mapping each event kind to the required parameters (GOAL + goalKey, BUTTON_CLICK + blockId, etc.), which is not obvious from the flat schema. It also reveals the error/discovery behavior for missing goalKey (returns the list of known goal keys), adding meaning beyond the schema's individual parameter descriptions. This justifies a score 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 immediately identifies the tool as a 'reverse lookup' for contacts who triggered a specific analytics event, with explicit enumeration of the four event kinds (GOAL, BUTTON_CLICK, BLOCK_SENT, BROADCAST_DELIVERED) and their required parameters. It distinguishes itself from list_contacts by stating 'prefer it over paging list_contacts and checking each one', making the unique purpose unmistakable.

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

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

The description provides clear when-to-use guidance: use this tool to find contacts matching an event, and explicitly prefers it over list_contacts for this scenario ('prefer it over paging list_contacts and checking each one'). It also gives conditional instructions per event kind (e.g., 'Omitting goalKey for kind GOAL fails with the list of known goal keys'), which helps the agent choose correct parameter combinations. The sibling list_contacts is named as the alternative, satisfying the explicit alternative 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 adds rich behavioral details: ordering by due time, that follow-ups send nothing by themselves, and the semantics of completionReason distinguishing manual vs platform closure. 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?

Four sentences with no redundant content. The core purpose is front-loaded, and the subsequent details about ordering, non-sending behavior, scopes, and completionReason each add distinct value.

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

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

The description covers core behaviors and scope semantics, and the schema fully documents parameters. However, with no output schema, it doesn't enumerate the return fields beyond completionReason, leaving a small gap for agents expecting a full response shape.

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

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

The schema covers all 7 parameters with 100% coverage, so baseline is 3. The description adds substantial context for the scope parameter, explaining each enum value and default behavior based on key type, which goes beyond the schema's short description.

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

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

The description states a specific verb and resource ('List follow-up tasks') and defines what a follow-up task is: reminders for a person to get back to a contact. It also includes read-only and ordering details, which distinguish it from create/update 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 clear context for when to use the tool (listing reminders) and detailed guidance on scope selection based on API key type, including default behavior. It does not explicitly name alternatives, but no competing list tool exists among siblings, so the read-only framing and scope instructions are sufficient.

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?

Beyond the readOnlyHint annotation, the description discloses the required view_logs permission, the bounded time window (default 24 hours, max 30 days), and the behavioral difference between raw rows and grouped rollups. This adds meaningful context about what the tool does and what the agent should expect.

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: purpose first, then permission, then mode semantics, then drill-down procedure, then window constraints, then alternative routing. It is well-organized and front-loaded with the most important information.

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

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

For a read-only log query tool with no output schema, the description covers all key operational aspects: permissions, window limits, grouping semantics, how to navigate from summary to detail, and when to use a different tool. The rich input schema covers the parameters, so nothing important 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 input schema already documents each parameter. The description adds useful context about groupBy semantics and window defaults, but does not need to restate parameter-level details. The baseline of 3 is appropriate because the description supplements rather than repeats 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 names a specific verb and resource ('Read the bot execution log (flow_execution_log)') and clearly distinguishes it from sibling read tools, especially get_contact_activity. It also explains the unique value of the log: separating 'the action ran' from 'the action produced output'.

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 guidance: two modes are described, with instructions to group by error/action/flow/day and then re-run without groupBy to inspect the rows behind a group. It also explicitly recommends get_contact_activity with includeFlowRuns as the narrower read for one contact's history, making the alternative selection clear.

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

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

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 readOnlyHint annotation: it discloses deterministic behaviour, AST simulation, that nothing is mutated, that scenarios can be inconclusive, that 'none' coverage means the run proves nothing, and that no real user traffic is involved. It also explains how `passed` can be misleading.

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

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

The description is front-loaded with the core purpose and usage order, and every sentence adds substantive detail. It is dense and somewhat sprawling, burying the applicationId caveat and coverage warning deep in the text, but it avoids fluff and is well organized in terms of smoke → scenarios → interpretation.

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

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

Covers the full invocation contract: what it does, when to call it, required inputs, optional scenarios, return shape, failure/caveat semantics, and permission-related behavior. An agent has enough information to decide when to use it, how to call it, and how to interpret the result.

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

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

The schema already documents parameters well, but the description adds meaning beyond it: `flowIds` should come from `apply_actions.idRemap`, scenarios are the only way to assert exact text, and applicationId has permission-dependent default behavior (`app_...` vs `usr_...`). This is valuable context the schema does not fully 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?

The description states a specific action — running deterministic behavioural tests against already-applied flows — with a concrete resource (flows), a clear mechanism (compile + simulate a user), and an explicit boundary (

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

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

The description gives explicit sequencing ('Call after apply_actions to verify a build') and explains when the optional scenario layer is needed ('the only way to assert exact texts'). It does not explicitly name alternative tools or state when not to use it, but the intended workflow and coverage caveats are clear.

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

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

Beyond annotations (readOnlyHint=true), the description adds that no API key is needed, that it returns compact matches without the flow body, and covers edge cases (no args, no matches). This enriches the agent's understanding.

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 adds value, front-loaded with purpose, no fluff. Efficiently covers purpose, usage, behavior, and edge cases in a compact paragraph.

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

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

Given no output schema, the description sufficiently explains return format (id, title, summary, tags) and that full body requires a separate tool. It does not detail pagination or sorting, but for a tool with limit parameter it's 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 coverage is 100% so baseline 3. The description adds context like 'combined with query' for tags and 'without filtering' for omitting query, and notes that limit values outside 1-8 are rejected. However, this adds minimal additional meaning beyond the 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 the tool searches a library of reusable flow examples covering common business cases, lists examples (lead capture, onboarding, payments, reminders), specifies returned fields (id, title, summary, tags), and distinguishes itself from get_flow_example for full details.

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

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

Explicitly says it's read-only, needs no API key, explains when to use get_flow_example instead (to get full example by id), and describes behavior with no arguments (returns top examples) and empty query (returns empty list, not error).

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 meaningful behavior: variable-name search returns referencing blocks despite blocks storing ids, matching is not tokenized, broadcast-backed flows and operation graphs are excluded, and the tool is read-only. It adds substantial behavioral context above the annotations and never contradicts them.

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

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

The description is long but information-dense; it enumerates search targets, explains the variable-name nuance, gives usage guidance, and lists exclusions without repetition. Every sentence contributes a distinct, actionable fact for 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?

For a read-only search tool with three documented parameters, the description covers the purpose, scope, parameter behavior, exclusions, and alternatives. It also surfaces edge cases like variable ids and personal-key application requirements are covered in the schema. Nothing critical for selecting and invoking the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds important query-parameter semantics by explaining that a keyword matching a variable name returns blocks referencing that variable, which plain text search cannot do. This goes beyond the schema's basic 'case-insensitive substring' note, though limit and applicationId semantics are left to the schema.

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

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

The description opens with a specific verb and resource: 'Find every flow and block whose contents contain a keyword.' It enumerates the exact searchable content areas and explicitly distinguishes itself from get_flow_context and list_broadcasts, so an agent can clearly tell what this tool does and does not cover.

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

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

The description gives explicit when-to-use guidance: 'Use this instead of walking flows with get_flow_context when you know what the content says but not where it lives.' It also states exclusions and the correct alternatives: 'Broadcast-backed flows and operation graphs are excluded — use list_broadcasts and the operations tools for those.' This is model guidance.

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

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

Beyond the annotations (idempotentHint=false, readOnlyHint=false), the description adds critical behavior: messages are not reversible and cannot be recalled, each contact is dispatched independently so partial failures occur, the runtime compiles flow on demand, duplicates are collapsed, and a required permission is necessary. No contradiction with annotations.

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

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

The description is verbose but each sentence serves a purpose; it front-loads the core action and then covers exclusions, edge cases, and error handling. A slightly tighter structure (reordering or bullets) would earn a 5, but given the complexity and side effects, the length is justified.

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

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

Importantly, there is no output schema, yet the description explains the result structure (results with sent/failed rows), prerequisites (fetch ids from apply_actions), constraints (max 50), permission, and reversibility. For a highly consequential send tool, this covers all critical non-auth context an agent needs.

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%, but the description enhances beyond the schema: it clarifies 'params' are run-scoped and missing required params reject the whole call, notes contactIds are FlowCastle ids not platform ids, and explains applicationId default behavior. This materially helps the agent avoid misuse.

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 precise verb and resource: 'Run an EXISTING interactive flow for each listed contact right now, outside any trigger'. It immediately distinguishes this tool from its sibling send_message by explaining the difference between the whole message being a flow vs custom text with buttons. No ambiguity remains.

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

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

It gives explicit when-to-use guidance ('Use it when the WHOLE message is the flow'), names the alternative (send_message with buttons), and explicitly says when NOT to use it (for large audiences: 'this is the WRONG tool'). It also explains rejected flow types (BROADCAST/OPERATION) and the correct alternatives.

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

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

Beyond the annotations, the description discloses asynchronous delivery, non-idempotence, irreversibility, the manage_broadcasts permission requirement, rejection of unsubscribed contacts, and where failures surface. It also advises confirming with the user and not blindly retrying, which is valuable 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 long but dense and front-loaded: the primary scoping decision comes first, then targeting, then media and button constraints, then side effects. Every sentence earns its place given the number of constraints an agent must respect.

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 mutating tool with no output schema, the description explains what a successful response means, preconditions, unsupported cases, and failure behavior. It gives an agent enough to call the tool correctly and safely.

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

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

Schema coverage is 100%, but the description adds key relational semantics: contactId is globally unique and preferred, platformId is per-bot and requires botId when ambiguous, placeholders resolve against the recipient's variable context, and each button must carry exactly one of url or flowId. These nuances go beyond the schema's field-level 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 opens with a specific verb and resource: 'Send a message to ONE contact right now, outside any flow.' It explicitly contrasts with broadcast for many contacts and with send_flow_to_contacts for whole flows, so the tool is clearly distinguishable from its 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?

It gives explicit routing guidance: use a broadcast for many contacts, use send_flow_to_contacts for a whole flow, and avoid unsupported combinations like buttons with media and flow buttons on SDK bots. This is clear when-to-use and when-not-to-use guidance.

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

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

The description discloses critical behavioral traits beyond annotations: full replacement semantics (omitting entries removes them), the permission requirement, the propagation delay (no restart needed), and the meaning of an empty list. These details enrich the agent's understanding beyond the idempotent and non-destructive hints, and do 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 description is dense but well-organized, front-loading the core purpose and then layering essential caveats (permission, SET semantics, entry requirements, update timing, empty-list warning). Every sentence adds unique value without redundancy, making it concise for the complexity involved.

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

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

The tool has no output schema and the parameter schema is fully detailed, so the description appropriately focuses on operational context. It covers permission, replacement semantics, entry constraints, the public_peek max, propagation delay, and empty-list behavior—making the tool fully understandable and safe to invoke.

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

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

Although the input schema covers all parameters (100% coverage), the description adds higher-level meaning: the complete-replacement list semantics, the need to call list_watched_groups first, and the behavioral constraints of public_peek. It does not duplicate field-level details but reinforces the overall intent, going beyond the baseline schema coverage.

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

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

The description opens with a specific verb ('Replace') and resource ('a telegram_mtproto userbot's watched-groups list'), clearly stating the tool's function and distinguishing it from the sibling list_watched_groups. It also explains what the list represents ('the chats it monitors') and mentions the required permission, leaving no ambiguity about the tool's purpose.

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

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

The description explicitly instructs to call list_watched_groups first and include existing entries to keep, providing direct usage guidance and setting clear SET semantics. It also clarifies the empty-list edge case ('NOT 'watch nothing'') and the public_peek limit, preventing common misuse. This effectively guides the agent on when and how to use the tool relative to its sibling.

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

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

Beyond the annotations, the description discloses concrete behavioral details: reads the dialog list live, connection required, may take up to a minute, creates missing contacts, leaves existing untouched, is idempotent, and does not affect watched-groups. This goes well beyond the idempotentHint annotation and clarifies side effects and prerequisites.

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

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

The description is moderately long but every sentence contributes new, useful information. It front-loads the core purpose, then packs permissions, performance, idempotency, side effects, and parameter guidance into a compact paragraph with no redundancy.

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

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

Given 4 optional parameters, no output schema, and good annotations, the description covers all key aspects: purpose, permissions, performance expectations, idempotency, side effects, and parameter usage. It leaves nothing critical unexplained for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples (kinds filter example: ["group","channel"]) and contextual notes (botId omission condition, limit tied to account size). While the schema already documents each parameter, the description enriches understanding of how to use them.

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

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

The description opens with a specific verb and resource: "Import a telegram_mtproto userbot's existing chats as contacts" and clarifies the intended effect (making them valid send_message targets). It also distinguishes from sibling tools by explicitly stating it does NOT change the watched-groups list, which separates it from set_watched_groups.

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 usage context: use when you want all existing chats to be send_message targets without waiting for each chat to message first. It states prerequisites (manage_broadcasts permission) and explains optional behavior (kinds filter, botId omission). It does not explicitly name alternatives like create_contact, but this is adequately implied by the purpose.

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 confirms annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and adds context beyond them: it notes the permission requirement, the partial update behavior (only passed fields change), and that it returns the updated application.

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), front-loaded with the purpose, and every sentence adds value: permission requirement, idempotency, and return value.

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

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

The description covers the essential aspects: purpose, permission, partial update, and return value. However, it does not mention error cases (e.g., invalid applicationId) or the default behavior for applicationId when omitted. Still, it is sufficient for a tool with no output schema and 100% schema coverage.

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 the input schema already has 100% per-parameter descriptions, the description adds collective behavioral meaning: 'Only the fields you pass are changed; omitted fields keep their current value, so the call is idempotent.' This provides context beyond individual parameter descriptions.

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

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

The description clearly states the verb 'Update' and the resource 'application-level settings', listing the specific fields (name, active state, default language, incoming-message behavior). It distinguishes from siblings like create_application and get_application_context by focusing on mutation.

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 specifies the required permission ('manage_settings') and explains idempotent behavior. However, it does not explicitly state when to use this tool versus alternatives like create_application, nor does it provide exclusion criteria.

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

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

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?

Annotations already indicate idempotent and non-destructive, but the description adds crucial behavioral nuance: changes affect the whole workspace, dismissals are visible to all members, dismissed items return after cooldown, and closing a card does not fix the underlying cause. No contradiction with annotations.

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

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

The description is dense but every sentence carries essential operational information. It front-loads the core action, then covers workspace-wide impact, recurrence behavior, cooldown, and the key exclusion of applying recommendations. No filler or redundancy.

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

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

Given seven parameters and no output schema, the description covers the critical operational context: workspace visibility, who is affected, persistence of state changes, cooldown behavior, and the limitation that proposed changes are not applied. The schema covers all parameter meanings, so nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100% and each parameter already has a rich description. The tool description adds meaningful behavioral semantics beyond the schema, such as 'dismissing a recommendation hides it from every member' and 'records who decided,' which enrich understanding of action and note 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?

Description opens with a specific verb and resource ('Change one Pulse item's state'), immediately clarifying the operation. It also distinguishes itself from read-only siblings like get_pulse_item and from apply_actions by explicitly stating it does not apply a recommendation's proposed change.

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 context on when each action is appropriate, including workspace-wide effects, cooldowns, and re-raising by detectors. It stops short of explicitly naming sibling alternatives and when to prefer them, but the 'dashboard action' contrast and action semantics provide clear practical 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, so the safety profile is covered, but the description adds meaningfully beyond that: it mutates nothing, is safe to repeat, and returns the same errors/warnings apply_actions would report. It also flags the important limitation that passing validation does not imply a sound design.

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

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

Front-loads the core purpose, then immediately qualifies it with the redundancy caveat and the design-quality caveat. Each sentence carries distinct, decision-relevant information with no filler.

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

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

Despite no output schema, the description states what it returns (errors and warnings), its safety profile, its relationship to apply_actions, and its limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents flowId, actions, applicationId, and conversationId in detail. The description adds no parameter-level syntax or format details, making the baseline 3 appropriate.

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

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

Opens with a specific verb+resource+mode: 'Dry-run validation of a proposed batch of flow-builder actions.' It distinguishes itself from apply_actions explicitly, so an agent can tell the two apart without opening a schema.

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

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

Gives explicit when/when-not guidance: calling it before apply_actions is redundant because apply_actions performs the same validation, so use it only for drafts you don't intend to apply yet. It also routes to get_design_guidelines for structural concerns.

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