FlowCastle

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

While annotations already indicate destructive/non-idempotent traits, the description adds substantial detail: non-atomic execution (partial success on mid-batch failure), validation-first behavior, irreversible side effects of run_operation (sends real broadcasts, writes application variables, cannot be undone), and confirmation requirements for deletions and run_operation. It also discloses the return shape including idRemap.

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, covering purpose, key alternatives, safety warnings, atomicity, idempotency, and retry guidance. It is front-loaded with the primary purpose and each segment earns its place. Slightly dense but acceptable for the tool's complexity.

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 supports over 20 action kinds and has no output schema, this description is remarkably complete. It covers validation, non-atomic execution, destructive actions, irreversible side effects, idempotency, retry guidance, and references auxiliary tools (get_action_schema, get_design_guidelines) for per-action contracts. It appropriately delegates detailed contract definitions to get_action_schema rather than enumerating them all.

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 meaningful context beyond the schema: it explains placeholder id usage in the same batch (flow_1, block_1, etc.), the broadcast-specific requirement to add message blocks in the same batch via data.flowId, and that idRemap maps placeholder ids to real created ids. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: 'Validate and apply a batch of flow-builder actions — the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders.' It uses a specific verb plus resource and distinguishes itself from the sibling tool validate_actions by explicitly saying a separate validation call is unnecessary.

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

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

It provides explicit guidance on when to use directly ('Call this directly; a separate validate_actions call beforehand is unnecessary'), explains that broadcasts have no dedicated tool and must be managed here, and advises reading get_action_schema and get_design_guidelines before structural edits. It also gives exclusion/retry guidance: 'never blindly retry a timed-out call... re-read state with get_flow_context before retrying rather than blindly resending the batch.'

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?

Annotations already provide readOnlyHint=true. Description adds that it's read-only, takes no arguments, and requires no API key, which is helpful context beyond annotations. 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 sentences: first explains content, second gives usage context. Front-loaded with purpose, no redundant 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?

Fully adequate for a tool with no parameters and no output schema. Description covers what is returned, when to use it, and its safe nature, leaving 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 in schema, so baseline is 4. Description adds no parameter info (unneeded) but describes the return value, which compensates for lack of output 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?

Description clearly states it returns the action-authoring contract with specific details (action kinds, fields, placeholders, syntax, block types). It distinguishes from sibling apply_actions by positioning itself as the schema reference.

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 'Read this before drafting any apply_actions batch', giving clear when-to-use guidance. Also notes it needs no API key, reinforcing its role as a prerequisite.

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

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?

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?

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?

The description adds substantial behavioral context beyond the readOnlyHint annotation, including pagination order (newest first), filter semantics (AND combination), search field scope, return content (compact summaries without variables), and a platformId uniqueness caveat. This is detailed and useful, with no contradiction to annotations.

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

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

The description is compact and information-dense, with the main purpose stated first, followed by filter behavior, return type, and a caveat. Every sentence contributes meaningful context without redundancy or 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 the tool's complexity (7 parameters) and absence of an output schema, the description covers essential aspects: pagination, sorting, filter combination, search breadth, return summary nature, and an important data-model caveat (platformId uniqueness per bot). It fully enables correct invocation and result interpretation.

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 covers all 7 parameters with descriptions, so baseline is 3. The description adds value by explaining that filters combine as AND and that search matches name, username, email, phone, and platformId—this cross-parameter behavior is not fully captured in individual schema descriptions. However, much of the search field list is repeated from the schema, so it is not maximally additive.

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 and search contacts in the application, paginated, newest first.' This clearly states what the tool does and differentiates it from the sibling tool get_contact by noting it returns summaries without variables. The scope and sorting behavior are explicit.

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

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

The description provides explicit guidance on when to use this tool versus an alternative: 'use get_contact for one contact's variables.' It also clarifies that filters combine as AND, which is a usage rule that helps the agent decide how to construct queries. This goes beyond simply stating prerequisites.

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

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

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

The description goes far beyond the annotations. It discloses permission requirements ('Requires the manage_broadcasts permission'), asynchronous delivery ('a successful response means the bot accepted the send, not that the platform delivered it'), irreversibility ('NOT idempotent and not reversible'), and real-world impact ('each call sends another message to a real person'). These details are not in the annotations and are essential for safe use.

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 a clear opening sentence and logically groups targeting, media, and warnings. It is long but each sentence earns its place for a high-impact tool. Minor redundancy exists (e.g., 'not reversible' and 'cannot be recalled' say similar things), keeping it from a 5.

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

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

For a tool with no output schema, the description compensates by explaining response semantics ('a successful response means the bot accepted the send'), error scenarios (candidate bots listing), media constraints, and safety warnings. Given the complexity and the real-world consequences, this description is fully complete 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 baseline is 3. The description adds meaningful context: it explains why 'platformId' is not globally unique with a concrete example, why 'botId' is needed, and clarifies media behavior (album grouping, caption length, extension inference). However, it duplicates some schema details and does not add nuance to 'applicationId', so a 4 is appropriate rather than 5.

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

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

The description clearly states 'Send a message to ONE contact right now, outside any flow', specifying the verb, resource, and scope. It explicitly distinguishes from siblings by directing many-recipient use to 'a broadcast instead', which differentiates it from broadcast-related tools.

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

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

Explicitly provides when to use ('right now, outside any flow') and when not to ('For reaching many contacts use a broadcast instead'). It also gives targeting alternatives ('contactId' preferred vs 'platformId') and critical exclusions like 'Not supported for SDK bots' and 'Unsubscribed contacts are rejected'.

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

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

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?

Annotations declare readOnlyHint=true, consistent with description. Description adds that it's safe to repeat, returns same errors/warnings as apply_actions, and warns that passing validation doesn't imply sound design—useful 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?

Three succinct sentences front-loaded with purpose and key behavior, zero wasted words. The redundancy note is placed early and is highly informative.

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 sibling tools (apply_actions, get_action_schema, get_design_guidelines), the description explains the tool's role perfectly. No output schema exists but return values are described. 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?

Schema coverage is 100% with detailed descriptions for each parameter. The tool description does not add new parameter-level meaning beyond what the schema already provides, so 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 clearly states the tool validates a batch of flow-builder actions as a dry-run, and explicitly says it mutates nothing. It distinguishes itself from sibling 'apply_actions' by framing as a safe check.

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 (checking a draft not intended to apply) and when not (redundant before apply_actions). Also contrasts structural rules with design guidelines linking to get_design_guidelines.

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