FlowCastle

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

Annotations already flag destructiveHint and non-idempotency, but the description goes far beyond them: it names which actions are destructive, that delete_operation also removes the hidden graph flow and run history, that delete_broadcast removes delivery history, that run_operation sends real broadcasts and writes variables and cannot be recalled, and it explains the validation-first / partial-revert model with the errorClass taxonomy.

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

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

Front-loaded with the identity of the tool and the single most important routing fact, and nearly every sentence carries decision-relevant content for a 32-action batch tool. It is still a dense block of prose with some repetition — user confirmation is advised three separate times, and non-idempotency is stated twice — which could be tightened with headings.

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 high-complexity, no-output-schema tool, it covers the return shape explicitly (success, validated, reverted, errorClass, changes, errors, warnings, actionId, plus idRemap), the failure/revert semantics, and the deploy boundary (edits land on the draft graph, live bots keep the published version). Nothing an agent needs to call it safely 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 real value by explaining the flowId default, how placeholder target ids are remapped via idRemap, and the update_block patch contract (omitted keys kept, lists replaced, explicit nulls refused on menu/triggers/actions/media). It stops short of documenting the validation or conversationId parameters beyond what the schema already says.

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

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

States a specific verb and resource ("Validate and apply a batch of flow-builder actions") plus explicit scope ("the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders"). This immediately distinguishes it from read-side siblings like get_flow_context and from the dedicated validate_actions tool.

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

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

Explicitly says to call this directly and that "a separate validate_actions call beforehand is unnecessary" — a rare, unambiguous exclusion of a sibling. It also routes to get_action_schema for the action contract, get_design_guidelines before structural edits, get_flow_context before retrying a partial write, and deploy_application to publish.

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 (which only flag readOnlyHint=false, idempotentHint=false), the description discloses the auth requirement, the side effect of seeding default flows, and the concrete non-idempotency consequence ('calling it twice creates two applications'). It also notes persistent state creation. This is exactly the extra behavioral context annotations cannot convey.

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

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

Four tight sentences, front-loaded with the action, then prerequisite, then side effects, then the return-value handoff. No filler and every sentence carries distinct 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?

There is no output schema, so the description compensates by naming the return value (the new application id) and its downstream use as applicationId. Combined with the auth and idempotency notes, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents name, skipDefaultFlows, and preferredLanguage in depth. The description restates the skipDefaultFlows default behavior ('Seeds default flows unless skipDefaultFlows is true') but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Create a new application (workspace) owned by the caller') and clarifies the 'application = workspace' terminology so the agent can map it onto the sibling list_applications/update_application family. It also states the return value and how it feeds other tools, leaving no ambiguity about what this call produces.

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 a concrete prerequisite ('Requires a personal API key (usr_...) — application-scoped keys cannot create applications'), which tells the agent when this tool will fail and therefore when to reach for it. It also explains what to do next with the returned id. It stops short of naming alternatives or explicit when-not-to-use conditions, so it is 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 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 declare non-idempotent and non-destructive, but the description adds the consequence ('calling it twice creates two reminders'), the delivery semantics (nothing sent when due), closing behavior, assignment semantics for personal vs workspace keys, and the lead-parking side effect with reasonText in lead history. That is substantial context no annotation field carries.

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

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

Front-loaded with what it is and the idempotency warning, and each sentence carries information. It is dense and somewhat long, with several clauses chained by semicolons, but nothing reads as 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 mutating, non-idempotent tool with no output schema, the description covers side effects, result shape on the lead path, permissions/assignment behavior, and lifecycle. An agent can call it without discovering these behaviors at runtime.

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 a baseline of 3 applies. The description earns a bump by tying reasonText to lead history when leads are on and explaining that the result may return task null, meaning the caller's assumption about a created task can be wrong even with valid 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 first sentence names a specific verb and resource (create a follow-up reminder for a person) and scopes it to contacting a person. It is immediately distinguishable from send_message and broadcast, both named later, and from the automatic 'no reply for N days' follow-ups.

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 routes the agent: 'use send_message or a broadcast to actually message someone' versus this tool which sends nothing. It also states the reminder stays open until completed, and that replies do not close it, which is exactly the exclusion an agent would otherwise get wrong.

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 that delivery is asynchronous, that a status of queued does not mean a runtime was restarted, that a version can be marked published while no runtime received it, and that callers must check error and per-bot status. It also explains idempotent repeat behavior and states the required manage_automation permission. These details are consistent with the destructiveHint=true and idempotentHint=true 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?

Although the description is longer than average, it is front-loaded with the core action and every sentence contributes operational value for a destructive, asynchronous deploy operation. There is no filler.

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

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

With no output schema, the description supplies the return shape, key fields to inspect, asynchronous status caveats, and permission requirements. Combined with annotations, it gives an agent everything needed to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already well documented in the schema. The description reinforces botIds subset publishing and default all-active-bot behavior, but adds little beyond what the schema provides for applicationId.

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: publishing the workspace to its bots, explicitly framed as the API equivalent of the dashboard Deploy button. It also distinguishes the tool from apply_actions by explaining that apply_actions writes to the draft graph while this makes edits live.

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 timing guidance: deploy after a batch of edits and after run_flow_autotest passes, not after every action. It names related tools and alternatives (apply_actions, run_flow_autotest, list_releases, restore_release) and advises confirming with the user before publishing unreviewed edits.

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?

Annotations already establish read-only safety, but the description adds useful behavioral context: no API key is needed, responses respect a budget by returning whole sections, truncation is surfaced through `omitted`, and referenced topics that did not fit appear in `alsoRelevant`. It also explains the session-sensitive `includeCore` behavior, which is exactly the kind of operational nuance annotations cannot capture.

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 key operational fact — read-only, no API key — is front-loaded, followed immediately by the no-argument index workflow. Despite covering index/detail modes, budget behavior, and specialized feature routing, every sentence carries useful information without 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?

There is no output schema, so the description carries the full burden of explaining return behavior. It does so by naming what the index contains, how detail responses work, how budget omissions are reported, and how `alsoRelevant` works, leaving no major ambiguity for an agent preparing 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 complete, so the schema already documents each parameter. The description nonetheless adds meaningful call-shape semantics by explaining that omitting all arguments returns an index and that subsequent calls should request only the bot's relevant items, which helps the agent understand how the optional arrays are intended to be used together.

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 resource and states the specific contract it exposes: the schema that `apply_actions` validation uses. It also distinguishes the no-argument index mode from targeted detail requests, making the tool clearly separate from `apply_actions` and `validate_actions`.

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

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

It explicitly tells the agent to call with no arguments first to get the index, then request only the topics/actions/block types actually used. It further directs the agent to follow `seeWhen` before specialized features and to re-request `omitted` names, giving clear sequencing guidance.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description still adds real behavioral context: the response 'grows with workspace size' (a scale/perf warning), hidden flows appear only in the operations list and never in flows, and the blockFallback* fields are explained as application-level defaults for failed ACTION blocks with a pointer to get_action_schema.actionFailure. These are non-obvious data semantics an agent could not infer from the schema.

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

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

Front-loaded with the purpose and the routing alternative, then details. The final sentence on blockFallbackStrategy is dense and slightly tangential to a 'get context' call, though it does explain fields the caller will receive, so it earns most of its space.

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

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

No output schema exists, so the description carries the return-value burden and does: it lists the response sections, flags the one structural gotcha (operations vs flows), and explains the meaning of a cluster of fields. Combined with full parameter docs, an agent has everything needed to call and interpret 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?

The single applicationId parameter is fully documented in the schema, including the app_ vs usr_ key defaulting rule and the MCP_APPLICATION_REQUIRED failure mode. The description adds nothing about it, but with 100% schema coverage 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 and resource ('Return the full application-level automation context') and enumerates exactly what that bundle contains: flows with folders, bots, variables, sequences, operations. It also positions itself against siblings by naming get_workspace_summary and describing the operations list as the home of hidden flow graphs.

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 frames itself as 'the broad orientation call' and states the alternative with its triggering condition: prefer get_workspace_summary when you only need names and counts. That is a clean when-to-use / when-to-use-something-else pairing rather than an implied one.

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, destructiveHint=false, and openWorldHint=false, so safety is covered — yet the description adds real behavioral context: this is the heaviest read in the API (a cost signal that shapes call strategy), and update_block's merge semantics (omitted settings kept, lists replaced wholesale). The round-trip guarantee that the returned payload can be sent back to update_block unchanged is a non-obvious, high-value property.

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

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

Front-loaded with the return contents, then cost guidance, then the update interaction — a sensible order. The final sentence is long and stacks three separate update_block rules, which costs a little readability, but every sentence carries distinct, non-redundant 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?

No output schema exists, and the description compensates by enumerating the returned payload categories and asserting the payload is update_block-compatible. For a 3-parameter read tool with full annotation coverage, nothing an agent needs to invoke and reuse 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%, and the schema itself thoroughly documents flowId, blockId, and the applicationId / MCP_APPLICATION_REQUIRED behavior. The description adds no parameter-level meaning beyond mentioning get_flow_context as the source of block ids, so the baseline of 3 applies — the schema is doing the work.

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

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

States a specific verb and resource ('Return the complete contents of one block') and then enumerates exactly what comes back: block data, action configs, HTTP bodies, custom-code files, triggers, menu payloads, media paths. That enumeration distinguishes it from sibling readers like get_flow_context, get_module_details, and get_action_schema without opening any schema.

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

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

Explicit routing instructions: call get_flow_context first to locate the block instead of walking a flow block by block, and always read a block before updating it. It names the load/cost tradeoff and the dependent tool (update_block), so the agent knows both when to use this and what must precede it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' is redundant; however, the description adds a genuinely non-obvious semantic caveat: 'Sent counts reflect messages attempted, not confirmed deliveries.' That prevents misreading of the returned numbers and is not derivable from any structured field.

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: payload definition first, safety class second, interpretation caveat last. Every sentence carries information and nothing is padded or repeated.

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

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

There is no output schema, so the description must characterize returns — and it does, naming both the status breakdown and per-block sent/clicked counts. The 'attempted vs confirmed' caveat covers the main ambiguity; only details like pagination or metric units are left unstated, which is minor for an analytics read.

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 broadcastId, applicationId, startDate, and endDate are all fully documented (including per-key default behavior for applicationId). The description only restates the existence of an optional date window, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Return engagement analytics for a broadcast', then enumerates the payload shape (delivery breakdown by status, per-message-block sent/clicked counts). This distinguishes it from siblings like get_broadcast_details (metadata) and get_flow_analytics (flow-wide), though it never names those alternatives explicitly.

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

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

'over an optional date window' implies the startDate/endDate use case and 'Read-only' tells the agent the operation class, but there is no explicit when-to-use guidance or steering toward get_flow_analytics/get_funnel_analytics for other analytical views. Usage is implied rather than directed.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description goes well beyond them: it warns that recipientCount is null when NOT COMPUTED and never zero, explains why filtered audiences are null until send time, and states that the tool reads delivery rows only. This is exactly the non-obvious trap an agent needs to avoid misreading a null as zero.

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

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

Front-loaded with the return payload, then the usage routing, then the recipientCount caveat. The null-semantics explanation runs three sentences and is slightly repetitive, but that nuance is genuinely load-bearing rather than 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 must carry return-value semantics itself — and it does, naming the fields and disambiguating the one field whose null is easy to misread. Combined with the sibling routing and prerequisite, an agent has everything needed to call it and interpret the result 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%, and the schema itself documents both broadcastId and the applicationId default/failure behavior (MCP_APPLICATION_REQUIRED), so the schema does the heavy lifting. The description only restates the list_broadcasts hint for broadcastId and adds nothing about applicationId; its null/recipientCount discussion concerns return values, not parameters. 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?

Opens with a specific verb+resource ('Return full details for a single broadcast') and enumerates exactly what is returned: status, schedule, recurrence rule, linked flow, and delivery breakdown. This clearly separates it from the plural sibling list_broadcasts and the engagement-focused get_broadcast_analytics.

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

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

States an explicit prerequisite ('Call list_broadcasts first to find the broadcastId') and an explicit alternative with the condition that selects it ('For per-message-block engagement stats use get_broadcast_analytics instead'). An agent can route between the two tools without guessing.

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 and destructiveHint=false, so 'Read-only' is partly redundant but confirms the profile. The description adds genuinely new context: returned values may contain personal data and SECRET-typed variables are always redacted, which is a behavioral trait the schema cannot express.

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

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

Four short sentences, each earning its place, with the return scope front-loaded and the prerequisite placed last where it is acted on. No filler or restatement of the tool name.

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

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

With no output schema, the description still states what is returned (full profile plus all contact-variable values), the redaction behavior on returns, and the prerequisite lookup. Nothing needed to call this two-parameter read 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 the schema already documents both contactId (including 'as returned by list_contacts or send_message') and the applicationId default/fallback behavior. The description's 'call list_contacts first' adds workflow framing but restates schema content, 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?

A specific verb ('Return') plus a precise scope: one contact's full profile and every stored contact-variable value. This clearly separates it from list_contacts and get_contact_activity, which an agent can distinguish without opening either schema.

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

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

'Call list_contacts first to find the contactId' gives an explicit prerequisite workflow. It stops short of stating exclusions or alternatives (e.g., when get_contact_activity is the better choice), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so "Read-only" is redundant, but the description adds real behavioral detail: ordering (newest first), separate per-stream capping, and the goalsTruncated/clicksTruncated signals that older events exist. It stops short of covering the applicationId/auth behavior (personal keys failing with MCP_APPLICATION_REQUIRED) and the includeFlowRuns permission, both of which live only in the schema.

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

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

Four compact sentences, front-loaded with what is returned and then layering sibling routing, exclusions, and capping semantics. Every clause carries information; nothing is padded.

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

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

There is no output schema, so the description carries the return-shape burden and does so: it names the event types returned, their ordering, the presence of all-time goal totals, and the truncation indicators. Combined with a fully documented input schema, an agent has what it needs to call this correctly.

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

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

Schema coverage is 100% and every parameter is documented there in detail, so baseline 3 applies. The description reinforces the `limit` semantics (goals and clicks capped independently, truncation flags) but adds no parameter detail the schema lacks, and it omits mention of startDate/endDate, applicationId, and includeFlowRuns entirely.

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

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

States a specific verb and resource ("Return one contact's engagement history") with an explicit scope: goals, clicks, all-time totals, newest first. It also names the sibling it is not ("per-contact companion to get_broadcast_analytics (which is aggregate)") and excludes non-events (typed replies, commands, website visits), so it is distinguishable from neighbors without opening schemas.

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

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

Gives a concrete when-to-use-vs-what: use this rather than get_broadcast_analytics when you need a single contact, and "Call list_contacts first to find the contactId" supplies the prerequisite step. The exclusion sentence ("typed replies, commands and website visits never appear") heads off a common wrong expectation.

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

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

Annotations already cover readOnly/safe/no-open-world, but the description adds what they don't: no API key needed, the two-phase index-then-full-text retrieval behavior, and the crucial caveat that a batch can pass validate_actions yet still be badly structured. That is genuine behavioral context an agent cannot infer from structured fields.

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

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

Front-loaded with purpose, then the call protocol, then the when-to-use warning; a compact example payload is included. Slightly dense and the index/two-call idea is restated more than once, but no sentence is filler.

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

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

No output schema exists, and the description compensates by describing the return shape twice over: a compact index containing short rules in full plus one-line pointers to every other section/example, then full text on the second call. For a zero-required-param, read-only reference tool, nothing needed 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 baseline would be 3; the description earns extra credit by explaining the usage pattern behind the params — omit both for the compact index, then pass ids taken from that index — and by clarifying examples/sections equivalence in context rather than as a schema note.

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 resource (flow-design rules that validation does NOT enforce) plus a precise scope of contents: branch-splitting, navigation/menu wiring, and worked examples. It is clearly distinguished from validate_actions by explicitly naming what validation misses.

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 timing ("Read this before any structural edit (new blocks, new branches, new flows)") and a concrete two-step procedure: call with no arguments for the index, then call again with only the sections the change touches. It also implicitly contrasts with validate_actions, which cannot catch structural problems.

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

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

Annotations already cover read-only/safe, but the description adds that results are computed on demand from the execution log and bounded to the last 14 days. It doesn't mention cost, latency, or behavior for flows with no executions, 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?

Front-loaded with the metric list, then the sibling differentiation, then the input sourcing and the read-only note. Dense but every sentence carries information; the metric enumeration is long though it is the payload the agent needs.

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

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

For a read-only analytics tool with full schema coverage and no output schema, this covers scope, time window, id sourcing, and the sibling boundary. The one gap is that return values aren't sketched at all, which matters slightly given 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 coverage is 100%, so both parameters, the 1-5 item bound, and the unknownFlowIds behavior are already documented. The description adds only where to source the ids, which is a mild but real addition over the schema.

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

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

States a specific verb (measure) and object (named flows) plus the exact metrics produced: entries, per-block stop rate, human handoffs, errors. It also explicitly contrasts with the sibling get_funnel_analytics and explains the scope difference (any flow vs. funnel-visible flows), so an agent can route without opening schemas.

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

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

Explicitly names the alternative (get_funnel_analytics) and the condition under which this tool is required (flows reached from a menu button, sequence, or operator handoff). It also tells the agent where to get the ids (get_workspace_summary or the flow index) and notes the 14-day window, which is a real usage constraint.

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 it discloses the deliberate cost/coverage trade-off, lists precisely what is omitted (block data, action configs, button/action/link/rule ids), and warns that *Preview fields are for reading and never for writing back. That is behavioral context an agent could not derive from annotations or 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?

Front-loads the return shape before the caveats and every sentence carries information. It is dense with parenthetical field lists, slightly long, but no sentence is filler.

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

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

No output schema exists, and the description fully compensates by describing the returned structure (including links[].to and menu.buttons[].to) and its truncation behavior. An agent knows what it gets, what it does not get, and where to go 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 already explains flowId provenance and the applicationId personal-key failure mode in detail. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return one flow's graph topology') and enumerates exactly what comes back: blocks in reading order, per-block summaries, and link/menu targets. It is clearly distinguished from get_block_details, which the description names as the deeper follow-up.

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 positions itself as 'the normal first step before editing an existing flow' and names the alternative ('once you know which block matters, call get_block_details'). Both the when-to-use and the hand-off are stated, leaving nothing to inference.

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

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

Annotations already cover readOnly/destructive/openWorld, but the description adds genuinely new context: no API key required, and the size trade-off of includeSchemaExample ('much larger'). That is useful behavioral disclosure beyond the structured fields.

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

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

Two sentences, zero waste, with the resource and scope front-loaded and the prerequisite/consumer constraints following. Every clause earns its place.

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

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

With no output schema, the description still tells the agent what comes back (example, optionally a full action batch) and how to obtain the id. Minor gaps remain around return shape, but it is sufficient to call 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 parameters are documented; the description still adds workflow meaning by framing the action batch as the artifact you adapt for apply_actions. It doesn't add syntax beyond the schema, so not a 5.

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

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

States a specific verb and resource ('Return one reusable flow example by id') and clarifies the optional action-batch variant. An agent can immediately distinguish it from search_flow_examples, which is named as the lookup counterpart.

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

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

Explicit prerequisite ('Call search_flow_examples first to find the id') and downstream consumer ('pass to apply_actions') give clear routing. There is no explicit when-not-to-use condition, which keeps it just below the top score.

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 and destructiveHint=false, and the description adds real context beyond them: computed on demand from the execution log, a fixed 14-day lookback, ordering, and the semantic of `dropoff` being null when nothing is bad enough. It also preempts a likely misread by explaining that a large `stopped` count on a flow's first block is normal, which is behavior an agent could not infer from schema or annotations.

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

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

Front-loaded with the purpose and ordered from output contents to semantics to caveats. Slightly overpacked, with minor redundancy such as 'Read-only' restating the annotation, but nearly every clause supplies distinct 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?

There is no output schema, so the description carries the burden of explaining return values, and it does: funnel stages, stop rates, `dropoff` selection rule and its null case, plus goal counts. Combined with the annotation-covered safety profile and a fully documented parameter, nothing needed to call it correctly is missing.

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

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

The single parameter is fully documented in the schema, including the app-versus-personal key default and the MCP_APPLICATION_REQUIRED failure mode, so description coverage is unnecessary. The description adds nothing about the parameter, which is the expected baseline at 100% 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?

States a specific verb and resource ('Return the measured conversion funnels') plus precise scope: entry flows only, 14-day window, busiest first. It enumerates the concrete quantities returned (entrants, blocks reached, stop share, dead buttons, goals) and defines 'entry flow' versus flows reached from menus/sequences, which lets an agent separate this from get_flow_analytics without opening either schema.

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

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

Gives a clear when-not-to-act rule ('Propose nothing when the funnels are healthy or too thin') and a scoping exclusion ('a flow reached from a menu button, a sequence or an operator handoff is NOT measured here'). It does not, however, name a sibling alternative for the unmeasured cases, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that the result is a summary only, listing what fields are included, and directing agents to get_module_details for action input fields and setup requirements.

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

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

The description is front-loaded and mostly efficient, covering purpose, read-only nature, usage routing, and return limitations in a few sentences. There is slight redundancy between the instruction to call get_module_details for exact input fields and the later note that action input fields come from get_module_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?

Given the absence of an output schema, the description explains what the return contains: module key, versions, description, actions, and triggers, and that it is a summary. It also clarifies follow-up steps and limitations. The only minor gap is that it does not describe applicationId behavior, but the schema fully covers that parameter.

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 applicationId parameter is fully documented in the input schema. The description does not add any meaning beyond the schema for this parameter, which is the expected baseline when schema coverage is 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 states a specific verb and resource: return a compact index of installed and available marketplace modules, including the fields each entry contains. It clearly distinguishes itself from sibling tools like get_module_details and install_module by explaining what it returns versus what they return.

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 tells the agent when to use this tool: when a capability is not covered by core action kinds. It also names the follow-up alternatives: get_module_details for exact input fields and install_module to add a module.

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 and destructiveHint=false, so safety is covered. The description still adds non-obvious behavior: an unknown moduleKey does not raise but returns an `error` string plus `availableModules`, and results are truncated with omissions surfaced via omittedActions. It does not mention auth/permission or versioning behavior beyond what the schema says, keeping it below 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?

Front-loaded with what is returned, then prerequisites, then error behavior, then response structure — a sensible order with no filler. It is dense and slightly overloaded with backticked field names in the final sentences, which costs it a point but every sentence carries 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?

There is no output schema, so the description must explain return shape, and it does: actionIndex first, actions for selective full reads, omittedActions for truncation, and error/availableModules on failure. Combined with the annotated read-only profile, an agent has everything needed to call and interpret 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%, so baseline is 3. The description still adds operational meaning to `actions` (read only some actions, omitted ones appear in omittedActions) and ties moduleKey to the catalog output, which the schema only partially conveys.

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

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

States a specific verb and resource ('Return everything needed to use one module') and enumerates the content: action input fields and types, trigger configuration, manual setup fields, installed action references. This clearly separates it from get_module_catalog (which returns keys) and get_action_schema (which covers a single action).

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 ordering rules: call get_module_catalog first to obtain moduleKey, and call this tool again after install_module to read installed action references. It also names the alternative/next-step tools rather than leaving routing to inference.

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

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

Annotations already cover read-only/non-destructive/closed-world, and the description reinforces 'Read-only' while adding the non-obvious resolutionPolicy semantics (automatic items self-close and cannot be resolved via update_pulse_item). That is real behavioral context beyond the annotations, though it stops short of describing response shape or any errors beyond the app-scoping note that the schema already carries.

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

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

Three tight sentences, front-loaded with the return contents, then the prerequisite call, then the subtle policy caveat. Nothing is redundant with the title or schema.

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

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

No output schema exists, so the description must describe return values — and it does, listing the evidence, related ids, and proposed change. Combined with the prerequisite and policy caveat, an agent has everything needed to call and interpret 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%, so both itemId and applicationId (including the MCP_APPLICATION_REQUIRED failure mode) are fully documented in the schema. The description only echoes the itemId prerequisite, adding no new parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Return one Pulse item in full') and enumerates exactly what comes back: measured evidence, conversation/execution-log ids, and any pending Apply change. This clearly separates it from list_pulse_items, which only lists.

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

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

Explicitly says to call list_pulse_items first to obtain the itemId, and routes the agent to update_pulse_item for the acknowledge/resolve distinction. Both the prerequisite and the sibling alternative are named.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is known; the description adds genuinely non-obvious traits beyond that: counts are DISTINCT contacts, results are computed on demand, and the window defaults to the last 30 days unless days is passed. It does not mention pagination or result-size limits for large surveys, which is the remaining behavioral gap.

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

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

Front-loaded with the core action and the mode split, and every sentence carries information — the dropoff-rate contrast justifies the tool's place rather than padding. It is on the long side (roughly seven sentences) and the mode descriptions could be tightened, but nothing is redundant with structured fields.

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

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

With no output schema, the description fully carries the burden: it describes the return shape in both modes (per-survey reach/answered counts and response rate, versus per-question option shares and verbatim answers). Combined with the default window, distinct-count semantics, and the schema's documented error for invalid flowId, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the behavioral fork of flowId ('Called with NO flowId it lists every survey flow... with a flowId it returns that survey per question') and the days default. splitGoalKey is left entirely to the schema, which documents it well, so the description does not add there.

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

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

States a specific verb and resource ('Read what customers ANSWERED... in surveys') and defines the resource precisely ('any flow marked isSurvey'). It also distinguishes the two operating modes (no flowId = listing, with flowId = per-question detail), which no sibling tool does, so an agent can separate it from get_flow_analytics or get_funnel_analytics.

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

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

Gives clear context for when this tool is the right evidence source, contrasting it explicitly with dropoff rate: 'far stronger than a dropoff rate, which only shows where people stopped and never why.' It stops short of naming a sibling tool to use instead when dropoff data is what's wanted, so there is no explicit exclusion or routing statement.

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

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

Annotations already declare this a read-only, non-destructive, non-open-world call, and the description layers substantial extra behavior on top: permission scope, one-hour expiry window, 60-second timeout semantics, and restart/offline invalidation. It stops short of describing the shape or possible values of the returned status/result, which is the one behavioral gap left.

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

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

Five short sentences, each carrying distinct operational information — identity, permission, cadence, expiry/timeout, and error handling — with the invocation essentials front-loaded. No filler and nothing restated from the annotations.

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

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

For a read-only polling tool with no output schema and only one required parameter, the description covers permissions, polling cadence, expiry, timeout, and runtime-restart invalidation, which is nearly everything needed to call it correctly. The missing piece is a hint at what the result payload contains or which status values to expect, which matters more given 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 coverage is only 33% (only applicationId is documented), so the description must compensate, and it does for the key constraint: both applicationId and botId must match the values used at submission. It does not say where requestId comes from (presumably the execute_telegram_operation response) or address the schema's MCP_APPLICATION_REQUIRED path for personal keys, so it compensates only partially.

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

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

States a specific verb and resource ('Read a Telegram operation status and result') and pins the identity keys (requestId plus the applicationId/botId used for submission). This implicitly separates it from execute_telegram_operation (the submitter) and list_telegram_operations (the enumerator) without the agent needing either schema.

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

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

Gives explicit operational routing: poll every two seconds, requires manage_broadcasts, results expire an hour after last update, and timed_out means no result within 60s and requires a fresh request if the runtime was offline or restarted. It also states the when-not path for throttling errors, directing the caller to respect error.retryAfterSeconds before submitting another 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the required manage_automation permission, explains that nextSteps is ordered and empty means ready to sell, and lists three setup actions that cannot be done by any tool. This adds meaningful behavioral and permission 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 front-loaded with the verb, resource, and returned fields, then adds permission and setup context without redundancy. The manual-steps sentence is long but high-value for an agent trying to understand what remains outside tool control.

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

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

There is no output schema, but the description enumerates the important returned setup fields and defines nextSteps semantics. Combined with the fully documented single parameter and safety annotations, it gives an agent enough information 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 description coverage is 100%, and the applicationId parameter is already fully documented in the schema, including app-scoped versus personal key defaults and the MCP_APPLICATION_REQUIRED failure mode. The description adds only an implicit 'of an application' scope, so the schema carries the 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 states a specific read operation on a specific resource: the Tribute one-time payment setup of an application. It enumerates the returned setup details (connection status, notification link confirmation, products, contact variables, nextSteps) and positions itself as the starting point for Tribute-related work.

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

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

It clearly says to start here for anything about Tribute and notes the manage_automation permission requirement, which gives useful invocation context. It does not explicitly route to or exclude sibling tools such as list_tribute_account_products, list_tribute_purchases, or update_tribute_connection.

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

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

Annotations only declare the read-only/non-destructive profile, but the description adds substantial context beyond them: values are withheld by default, list values are truncated to 500 characters, secrets stay redacted regardless, and the result set can be cut off. The truncation-detection recipe (compare returned against total) is behavior an agent could not infer from the schema.

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

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

Dense but front-loaded: purpose, return shape, truncation handling, value semantics, secrets, and reference syntax in order of likely need. Five clauses is near the ceiling, and a couple of details (secret redaction, personal data) are stated twice across description and schema, but nothing is wasted.

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

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

There is no output schema, so the description carries the return contract itself and does so well ({ variables, total, returned, truncated }). The only residual gap is that it doesn't describe the shape of individual variable objects (id, name, path, type, scope), which matters for assembling {{var|<id>}} references.

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 a baseline of 3 applies, but the description adds cross-parameter meaning the schema states only partially: variableId + includeValues yields the full value while a list yields previews, and scope/query/limit are ignored in single-read mode. It also flags the personal-data tradeoff of includeValues.

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

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

The description gives a specific verb and resource plus both operating modes ('search variable definitions by scope and keyword, or read one variable by id'), which no sibling tool covers. It also implicitly distinguishes itself from update_variable by naming that tool as the mutation counterpart.

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

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

Explicit when-to-use guidance is present for every mode: omit query to list, use variableId to read one, set includeValues only when the data is needed, and re-call with a higher limit when returned < total. It also prescribes a workflow ('read it this way before update_variable'), which is exactly the kind of routing an agent needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' sentence is partly redundant, but the description adds real behavioral context: the terminal status set, the polling loop, and the fact that warnings and non-imported pages are reported. It does not say what happens for an invalid or expired jobId.

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 resource and the returned payload, followed by the operational guidance. No filler or restating of the tool name.

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

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

With no output schema, the description carries the burden of describing the response, and it does so by listing stage, progress, counters, warnings and failed pages. The only gap is error/expiry behavior for the job id, which an agent would otherwise have to discover at runtime.

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 applicationId fallback/error behavior (MCP_APPLICATION_REQUIRED) is already documented in the schema, so the description adds nothing about parameters. Baseline 3 applies.

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

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

States a specific verb and resource (status of a website import) and enumerates the returned content: stage, progress, counters, warnings, skipped pages. It also anchors the tool to the exact sibling calls (import_website_knowledge / import_website_into_knowledge_base) that create the job, so the agent can tell which flow it belongs to.

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

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

Explicitly prescribes the calling pattern: poll this tool until status is DONE, DONE_WITH_ERRORS or FAILED, which tells the agent both when to call and when to stop. It stops short of naming when not to call it or what to do instead for edge cases (e.g. unknown/expired job ids).

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 declare readOnlyHint/destructiveHint/openWorldHint, and the description reinforces this with 'Read-only, no side effects' while adding the genuinely new disclosure that variables and full flow graphs are excluded from the output. This is valuable scope-of-return context, though it says nothing about response size or pagination-like limits.

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, then the alternative routing. Every clause (including the omission list) does work 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?

With no output schema, the description compensates by naming the entity types returned and the entity types excluded, and the annotations carry the safety profile. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters already document their own narrowing and defaulting behavior (including the MCP_APPLICATION_REQUIRED failure for personal keys). The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Return a compact ... summary') and enumerates exactly what is summarized: application, flow, sequence, operation, bot. It also draws a clear boundary against siblings by naming what the tool deliberately omits.

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 frames itself as 'the cheapest way to orient in a workspace' and routes the agent to three named alternatives (get_variable_context, get_flow_context, get_application_context) with the condition that selects each. Nothing is left to inference.

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

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

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 and destructiveHint=false, so the description adds value by disclosing the return shape ({ id, name, role, permissions }) and the meaning of an empty array (key valid but no application bound). What it does not cover — pagination, ordering, error behavior on invalid keys — is minor for a zero-arg read, so a 4 rather than 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?

Four short sentences ordered by utility: what it returns, when to call it, invocation cost, then the response contract. Every sentence carries a distinct fact and the routing guidance 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 zero-param, read-only tool with no output schema, the description supplies the missing pieces an agent needs: the response fields, the empty-array interpretation, and its bootstrap role for personal API keys. Nothing required to call or interpret it is absent.

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

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

With zero parameters the baseline is 4, and the description reinforces this by stating 'takes no arguments', removing any doubt about how to invoke it. No additional parameter meaning is needed because none exist.

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

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

States a specific verb and resource ('List the applications this API key can access') and immediately scopes it to the caller's role and permissions. It is unmistakable against siblings like list_contacts or get_application_context because it defines the access-discovery role rather than a domain listing.

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

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

Explicitly says when to use it: 'Start here when using a personal API key (usr_...)'. It also names the dependency that selects it — every other tool needs an explicit applicationId, which only this tool supplies — giving the agent both the trigger and the downstream consequence.

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/destructiveHint=false, so "Read-only" is redundant, but the description adds real behavioural context: newest-first ordering and the eventual-consistency rule that a chat only appears once the bot has been added. It does not mention pagination or result limits, which is the main remaining gap for a list operation.

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

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

Purpose and return shape are front-loaded in the first sentence, followed by compact behavioural notes. It is dense but every sentence carries information; the redundant "Read-only" is the only wasted clause.

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

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

With no output schema, the description properly compensates by naming the returned fields and their meaning (numeric chatId for flows, admin/invite/remove rights). Combined with the schema's documented optional filters, an agent has enough to call it; only pagination/volume behaviour is unaddressed.

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

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

Schema description coverage is 100%, so botId, kinds and the applicationId/MCP_APPLICATION_REQUIRED failure mode are already fully documented in the schema. The description adds no parameter-level guidance of its own, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ("List the groups and channels the application's bots were added to") and even enumerates the returned fields (title, kind, chatId, added time, admin rights), so an agent knows exactly what comes back. It does not name or contrast a sibling tool (e.g. list_watched_groups or list_telegram_operations), so differentiation relies on inference from the resource wording.

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

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

"Use this instead of asking the owner for a chat ID" gives a clear positive trigger and rules out a competing behaviour. It also explains an interpretation case ("when the owner's chat is missing, the bot is not in it yet"), but offers no explicit when-not or alternative-tool routing among the many list_* siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only' without contradicting. It then goes well beyond annotations: delivery counts are attempts not confirmed deliveries, recipientCount is delivery rows once sending starts, and null means NOT COMPUTED never zero, explaining exactly why filtered audiences and get_broadcast_details yield null. This is precisely the semantic context an agent needs to avoid misreading results.

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

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

Front-loads purpose and the read-only note, then layers semantics and alternatives. It is dense and long, but nearly every sentence carries distinct information (null semantics, AND combination, action routing). The recipientCount/null passage is slightly dense and could be tightened, 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 6-parameter list tool with no output schema, the description covers purpose, filtering semantics, return-value pitfalls (null vs zero), and sibling alternatives. An agent has everything needed to call it correctly and interpret the counts.

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 is documented in the schema, so the baseline is 3. The description adds genuine cross-parameter meaning the schema lacks — 'Filters combine as AND' — which materially affects how an agent composes botId, status, and isRecurring, though it doesn't comment on paging or the applicationId failure mode beyond what the schema already states.

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 (List) and resource (broadcasts) plus the fields returned (status, schedule, delivery counts). It also explicitly names the siblings it is not — get_broadcast_details for one broadcast, apply_actions/create_broadcast for creation — so an agent can route without opening any schema.

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

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

Gives explicit use/use-not routing: 'Use get_broadcast_details for one broadcast's full breakdown' and 'To CREATE or SEND a broadcast use apply_actions', down to the specific actions and status. It covers both the read-side alternative and the write-side path the agent would otherwise guess at.

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

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

Annotations already declare read-only and non-destructive behavior, but the description adds substantial operational context: newest-first pagination, AND-combined filters, exact tag-name matching behavior, the meaning of total, compact return payloads without variables, and the platformId uniqueness caveat per bot.

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 and scope are front-loaded, followed by filter semantics, return behavior, and one important identity caveat. The description is dense but every sentence earns its place and there is no filler.

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

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

Given ten optional parameters, rich schema coverage, and annotations covering safety, the description supplies enough additional context about ordering, filtering, return shape, and platform identity to call the tool correctly. No output schema exists, but the description adequately explains that results are compact contact summaries.

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 ten parameters well. The description still adds value by explaining UTM tag naming for tags/tagIds and clarifying that total is the full match count, though it leaves some parameter-specific details such as applicationId behavior 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: 'List and search contacts in the application,' and immediately qualifies scope with pagination order. It clearly distinguishes itself from get_contact by saying it returns compact summaries while get_contact is for one contact's 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?

It names useful alternatives: use get_contact for a single contact's variables and list_contact_tags to discover UTM tags. It also explains filter combination semantics. However, it does not explicitly state when not to use this tool versus related list tools such as list_event_contacts or list_bot_chats.

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 destructiveHint=false, so the 'Read-only' sentence is largely redundant. The description does add genuine behavioral context beyond annotations: only tags attached to at least one contact in scope appear, results are ordered most-used first, and it explains how 'utm: <slug>' tags are created. Pagination/truncation behavior at the limit cap is not described, keeping this at a 3.

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 most important facts — scope, ordering, read-only — are front-loaded in the first sentence. Five sentences is on the longer side and the parenthetical about '?start=utm--<slug>' deep links is dense, but each sentence carries information an agent would otherwise have to infer.

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

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

With no output schema, the description still tells the agent what the result contains (tag names plus contact counts, most-used first, excluding unused tags), which is exactly the missing piece. Combined with fully covered input parameters and clear annotations, nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100%, so botId, limit, search, and applicationId are already fully documented, including the MCP_APPLICATION_REQUIRED failure mode. The description adds domain meaning about what tag values represent (UTM slugs vs. manual segments) but nothing new about parameter syntax or defaults, so the baseline 3 applies.

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

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

Names a specific verb and resource ('List the contact tags in use') and immediately scopes it ('in the application (or one bot) with how many contacts carry each, most-used first'). It also distinguishes itself from the sibling list_contacts by framing this as the aggregate 'attribution view' rather than a per-contact listing.

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 routes the agent: use this for the tag inventory, then 'Pass a tag name to list_contacts `tags` to page through or count its contacts.' It also distinguishes UTM attribution tags from manual/flow-assigned segments, so the agent knows which tag family it is looking at.

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

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

Annotations already cover read-only/non-destructive, and the description adds real behavioral context on top: pagination, ordering by each contact's most recent matching event, SQL-over-event-tables execution, safety on large workspaces, and the exact failure mode when goalKey is missing. That is more than the safety profile the 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?

Front-loaded with the core identity, then the per-kind contract, then the routing advice. Every sentence carries new information — no restatement of the name or schema.

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

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

For a 13-parameter tool with no output schema, the description covers conditional requirements, pagination, ordering, and failure behavior, which is nearly everything needed to call it correctly. It does not describe the shape of each returned contact, a minor gap given 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 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema states only per-field: which parameters are conditionally required per event kind and that omitting goalKey yields a helpful error listing valid keys. It stops short of explaining interaction details like startDate defaults for each kind.

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

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

States a specific verb and resource ('which contacts triggered one analytics event') and enumerates the four event kinds with their required discriminators, so an agent knows exactly what this returns. It also explicitly distinguishes itself from list_contacts, naming it as the slower alternative.

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 an explicit routing rule ('prefer it over paging list_contacts and checking each one') plus per-kind conditions (goalKey for GOAL, blockId for BLOCK_SENT/BUTTON_CLICK, broadcastId for BROADCAST_DELIVERED). It even documents a discovery workflow: omit goalKey to get the list of known keys.

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 read-only annotations, it discloses that results are ordered by due time so overdue work comes first, that follow-ups do not send messages, and that `scope.narrowedToOwn` signals permission-based narrowing. It also explains `completionReason` semantics, separating human closure from platform closure.

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 and front-loaded, starting with the core purpose and read-only nature before scope details. It is somewhat long as a single paragraph, but nearly every sentence carries useful behavioral or permission context.

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

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

For a complex permissioned listing tool with no output schema, the description covers scope behavior, default behavior, narrowing signals, ordering, and completion semantics. An agent has enough information to choose a scope and interpret key edge cases 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, but the description adds meaningful semantics for `scope`, explaining permission widening, default behavior, and fallback behavior beyond the schema enum. It does not add much for `page`, `limit`, `origin`, `search`, or `timing`, which remain schema-documented only.

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

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

The description states a specific verb and resource ("List follow-up tasks") and immediately defines what the resource means: reminders for a person to get back to a contact. It also distinguishes the tool from its create/update siblings through its read-only, listing nature and by explaining that a follow-up sends nothing by itself.

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

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

It gives explicit scope-selection guidance for `mine`, `unassigned`, `team`, and `completed`, including the permissions each scope requires and how results narrow for personal keys. It also states the default scope behavior separately for personal and workspace keys, leaving little for an agent to infer.

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 destructiveHint=false, and the description reinforces 'Read-only' plus adds meaningful context: items carry measured evidence while source records stay in place, and the default status filter is 'open'. It does not cover pagination behavior or what happens with includeDismissed/snoozed semantics beyond the schema wording, so not a full 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?

Front-loads the resource definition and kinds, then defaults/ordering, then routing to siblings — a logical order with no filler. It is fairly dense (several clauses per sentence), which costs a point versus a leaner version, but nothing is wasted.

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

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

With 9 optional parameters, no output schema, and no nested objects, the description supplies the conceptual return shape (items with measured evidence, ordered by severity then due time) and points to siblings for detail and mutation. It leaves return-value specifics implicit, but no output schema exists to lean on, so a small 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 description coverage is 100% and each parameter already has a rich description (kind, status defaults, applicationId auth failure mode, category guidance). The description only echoes the default-open behavior and severity ordering, so baseline 3 is appropriate — the schema does the heavy lifting.

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

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

States a specific verb+resource ('List Pulse items') and immediately defines the resource as 'the workspace attention queue' with its two kinds, attention and recommendation. An agent can tell this apart from get_pulse_item (single item) without opening either schema.

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

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

Explicitly routes: use get_pulse_item for one item's full evidence, update_pulse_item to close one, and read_messages/query_flow_logs for the underlying conversations and logs. It also states the default view (open items, severity then due-time order, matching the dashboard).

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, so the description focuses on what the annotations can't say: the ordering (newest first), the access requirement, and the meaning of each returned field including liveBotIds. It adds substantive context beyond the annotation profile.

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 action and ordering are front-loaded, and the parenthetical release/enum definitions are dense but purposeful. Every sentence contributes, though the field-by-field enumeration makes it longer than strictly necessary for a list tool.

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

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

There is no output schema, so the description carries the burden of describing returned fields, and it does so thoroughly (number, origin enum, note, counts, liveBotIds). Combined with the access note and restore routing, an agent has everything needed to call and interpret 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% and the single optional applicationId is fully documented in the schema, including the personal-key failure mode. The description adds no parameter detail, which is acceptable at baseline when the schema does the work.

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

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

Specific verb+resource ('List the application's releases, newest first') plus an explicit definition of what a release is. It clearly distinguishes itself from restore_release, which it names, so an agent can separate listing from restoring 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?

'Use restore_release to put one back' routes the agent to the sibling for the downstream action, and 'Requires view access' states a prerequisite. It doesn't cover when to prefer other listing tools or what to do if the list is empty, so it falls short of a full when/when-not treatment.

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

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

Goes well beyond the annotations: discloses the required permission (manage_broadcasts), confirms no network call to Telegram is made (reinforcing the openWorldHint=false claim), and states that all catalogued operations read public data only. The mention of input schemas, permissions and limits also conveys what the response contains, which matters since no output schema exists.

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

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

Three compact sentences, each carrying distinct information: purpose, permission prerequisite, no-connection caveat, and the botId defaulting rule. The most decision-relevant facts come first with zero filler.

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

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

For a zero-required-parameter read-only catalog with no output schema, the definition covers what the tool returns and the one non-obvious parameter rule. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is only 50%, but the description compensates for the undocumented botId parameter by explaining it may be omitted when the application has exactly one userbot. applicationId is already fully specified in the schema, including the MCP_APPLICATION_REQUIRED failure mode, so both parameters end up covered.

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 ("Discover") and a concrete resource (supported Telegram MTProto account operations, their input schemas, permissions and limits). An agent can distinguish this catalog from execute_telegram_operation or get_telegram_operation by the "discover/catalog" framing, though no sibling is named explicitly.

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

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

The description establishes the prerequisite ("Requires manage_broadcasts") and the important scope caveat ("this catalog does not connect to Telegram"), which implies it is a discovery step rather than an execution step. It never explicitly says "use execute_telegram_operation to actually run one," so the when-to-use routing is left to inference.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds the permission gate (manage_automation), pagination shape and ordering, and the two failure modes (TRIBUTE_NOT_CONNECTED, TRIBUTE_UNAVAILABLE). It also explains that each returned product reports setup eligibility and current setup state, which is behavior the annotations cannot convey.

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

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

Four sentences, front-loaded with purpose and scope before pagination, permissions, errors, and the boundary note. Each sentence carries distinct information with no repetition of the schema or annotations.

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

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

With no output schema, the description steps in to describe both the return content (per-product setup eligibility and status) and the error surface. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, and the applicationId defaulting rules for app_ vs usr_ keys are already fully documented there. The description only adds the page-size and newest-first ordering context, which is mild added meaning, 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?

States a specific verb and resource ('List the digital products in the owner's connected Tribute account') along with scope details: live read, 100 per page, newest first. It also carves out what it is not ('Products are created, priced and approved in Tribute, not here'), separating it from save_tribute_product and the purchase-listing siblings without needing the schema.

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

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

Gives clear operating context: requires manage_automation, is read-only, and should be paged ('Ask for the next one while hasMore is true'). It never names an alternative tool explicitly nor states when not to call it, so it stops short of full routing guidance.

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

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

Annotations already cover readOnly/destructive/openWorld, yet the description still adds real behavioral detail: required scope, fixed page size of 50, newest-first order, and what each row contains including the human-delivery reason.

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

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

Four short sentences, front-loaded with what is listed and in what order, then safety/scope, then row shape and the empty-result interpretation. No filler.

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

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

With no output schema, the description usefully explains the returned rows, the delivery-reason field, and what an empty list means. Only minor gaps remain, such as the hasMore/pagination interaction, which the schema covers.

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 documents offset semantics and the app_/usr_ key default better than the description does. The description only contributes the 50-per-page fact that makes the offset hint usable, so the baseline 3 applies.

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

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

States a specific verb and resource (list Tribute payments), scopes it to the application, and adds ordering plus page size ('newest first, 50 per call'), which immediately separates it from the sibling products tool.

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

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

Gives the required scope (read_payments) and clarifies the empty-list case, which is genuine usage context, but it never names an alternative or says when another tool (e.g. list_tribute_account_products or retry_tribute_delivery) is the better pick.

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 and non-destructive, so safety is covered; the description adds real behavioral substance beyond that — unlisted groups are dropped, their contacts never materialize, and DMs bypass the filter. It stops short of describing the returned shape or ordering, which is a minor gap for a list tool with no output schema.

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

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

Four tight sentences with no filler; the core purpose and read-only constraint come first and the fail-closed semantics follow. Slightly dense but every sentence carries 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 zero-required-param read tool, the description covers purpose, safety posture, filtering semantics, and the botId default — enough to call it correctly. The missing piece is the relationship to list_bot_chats and set_watched_groups, which would complete the picture.

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 both parameters are fully documented in the schema. The description only echoes the botId omission rule already present in the schema and says nothing about applicationId defaulting, so baseline 3 applies.

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

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

States a specific verb and resource ('List the group/channel chats a telegram_mtproto userbot monitors'), which is far more precise than the bare name. It does not, however, distinguish itself from the sibling list_bot_chats, so an agent still has to infer which listing is which.

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 'what this means' context (fail-closed filtering, DMs always pass) but never states when to call this versus list_bot_chats or the paired set_watched_groups. Usage is implied by the source-of-truth framing rather than explicitly routed.

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

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

Annotations cover the read-only/safety profile, but the description adds context they cannot: the required view_logs permission, the bounded window (24h default, 14-day ceiling), and full redaction rules (query values as ?param=***, bodies truncated to 200 chars, SECRETs masked) with the important caveat that a masked value is not a missing one. It also discloses the two distinct row populations — runtime rows and deploy compile warnings — with their metadata.stage and deliverySkipReason conventions.

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

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

Front-loaded with the purpose and the two modes, then supporting detail, which is the right ordering. It is long, and the trailing enumerations of compile-warning and runtime-warning codes read as a reference dump that an agent rarely needs in full before calling, costing some conciseness.

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 twelve-parameter read tool with no output schema, the description still conveys enough about returned row shape (action, level, metadata.stage, metadata.deliverySkipReason, grouped vs raw results) and about window and redaction behavior that an agent can call it correctly and interpret results without further documentation.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning the schema does not: the mode switch on groupBy and which dimension answers which diagnostic question. It does not add much for the other eleven filters, which the schema already documents well.

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

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

Names a specific verb and resource (read the bot execution log / flow_execution_log) and immediately frames its unique value: it is the only place that separates 'the action ran' from 'the action produced output'. It also names the sibling that covers the narrower case, so an agent can distinguish the two without opening either schema.

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

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

Explicitly splits two modes — raw rows without groupBy, grouped rollup with groupBy — and prescribes which grouping answers which question (`error`, `action`, `flow`, `day`) plus the drill-down workflow (re-run with the same filters and no groupBy). It also names the alternative, get_contact_activity with includeFlowRuns, and the condition that selects 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 say read-only; the description adds the provenance of the data (runtime ledger written pre-routing, so untriggered inbound messages are included), the text-only limitation with caption substitution for media, button taps being absent, redaction after the retention window leaving text null, and a view_logs permission requirement with a PII warning. That is substantial context beyond the annotations.

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

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

Front-loaded with what the resource is, then filtering, paging, exclusions, retention, and permissions in a logical order. It is a single dense paragraph of roughly 170 words; nothing is filler, though the sentence listing every filter is close to restating the schema.

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

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

For a 9-parameter read tool with no output schema, the description covers return shape (newest first, nextCursor, text possibly null), retention behavior, permission prerequisites, and the sibling to use for excluded data. An agent has what it needs to call this correctly and interpret 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 coverage is 100%, so the baseline is 3, but the description adds framing value: which parameter selects a conversation vs a channel vs one side, that actor_type is narrower than direction, and that the returned nextCursor is fed back as `cursor`. It also explains the read scope when botId is omitted.

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

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

States a specific verb and resource ('Read the message transcript') plus both sides of the conversation and the sort order (newest first). It also draws an explicit boundary with a sibling ('Button taps are NOT messages... use get_contact_activity'), so an agent can separate this from other read tools without opening the schema.

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

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

Gives concrete filtering recipes per parameter, explains the cursor paging loop, and names the alternative tool for a nearby-but-different data type. It stops short of contrasting with list_bot_chats or query_flow_logs, so not every sibling choice is resolved.

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

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

Annotations cover only the safety profile (destructive, idempotent, openWorld); the description adds substantial context beyond them: the RESTORE_SAFETY release created or reused, how to undo via safetyReleaseNumber, soft-deleted steps retaining message history and contact values, application variable values left untouched, and the assistant-lock refusal. This is exactly the deeper behavioral disclosure the annotations cannot 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?

Front-loaded with the core action and its guarantees, and every clause carries operational information (safety release, soft deletes, publish semantics, lock, permission). It is dense but unbroken prose, which makes it harder to scan than it could be.

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

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

No output schema exists, and the description compensates by naming the returned safetyReleaseNumber and its undo role. Permissions, refusal conditions, mutation scope, and the confirm-with-user requirement are all present, so an agent has everything needed to call this destructive tool 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%, so the baseline is 3, but the description adds real meaning for publish by explaining what the default actually means operationally (nothing is promoted until deploy_application, unless publish=true). releaseId and applicationId are left to the schema, which already documents them well.

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

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

States a specific verb and resource ('Put an earlier release back into the editor') and immediately scopes what is restored (every flow, step, menu, action and variable, under the same ids). This clearly separates it from siblings like deploy_application, list_releases, and update_application.

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 default behavior (bots keep running until deploy_application), when to use publish=true (rollback of a broken publish), the refusal condition (AI assistant is changing the bot), the permission requirement, and the imperative to confirm with the user. Alternatives and preconditions are all named.

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

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

Adds real behavior beyond annotations: required scope recover_payments, the fact that it enqueues rather than delivers synchronously, and the specific failure code for review-pending payments. Annotations cover safety/idempotency, but the description does not explain why destructiveHint is true (i.e., that a retry actually moves money), leaving that risk implicit.

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

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

Four short sentences, every one carrying distinct information: action, precondition, permission, async semantics, follow-up, and refusal case. Front-loaded with the action, zero filler.

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

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

For a two-parameter mutation with no output schema, it covers prerequisites, permission requirement, async behavior, how to verify the result, and the known error path. Nothing further is needed to call it correctly.

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

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

Schema coverage is 100%, including the applicationId defaulting rules and the purchases[].id source, so the schema does the heavy lifting. The description only indirectly adds selection criteria via 'paid but not delivered' and 'reviewReason', which roughly maps to filtering purchaseId; baseline 3 applies.

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

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

States a specific verb and resource ('Queue one Tribute payment for delivery again') plus the qualifying scope ('a payment that was paid but not delivered'). An agent can immediately distinguish this from list_tribute_purchases, which is named as the read-side counterpart.

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

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

Gives a clear precondition (paid but not delivered), a post-call step (read list_tribute_purchases afterwards), and an explicit refusal condition (TRIBUTE_REVIEW_REQUIRED when a reviewReason exists). It does not name an alternative tool for the review-blocked case, which is the only 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 description adds substantial behavioural detail beyond the readOnly/destructive annotations: it says nothing is mutated or sent to real users, explains what the smoke layer does, lists the report fields, clarifies how harness gaps and 'none' coverage should be interpreted, and describes how unanswered outside GET calls are handled from recorded responses.

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 and front-loaded: purpose, usage, smoke behavior, scenarios, and return shape arrive in a logical order. It is longer than ideal, but nearly every sentence carries operational meaning for a complex simulator tool.

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

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

Given the complexity, lack of an output schema, and rich annotations, the description is complete enough: it explains the return keys, the distinction between scenario failures and harness gaps, coverage 'none', and the mocked/recorded outside-call behavior. An agent has enough context to call it correctly and interpret results.

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

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

Schema coverage is 100% and the schema already documents parameters in depth, so the baseline is 3. The description still adds high-level selection semantics: flowIds are the already-applied flows normally from idRemap, scenarios are optional journeys capped at 6, and scenarios are the only way to assert exact texts or stored values.

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: it runs deterministic behavioural tests against already-applied flows by compiling them to an AST and simulating a user. It clearly distinguishes the tool from apply_actions and validate_actions, and an agent can tell it is a verification step rather than a mutation 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?

It explicitly says to call after apply_actions to verify a build, then patch and re-run. It also explains when to use the smoke layer alone versus when to pass scenarios, and notes that scenarios are the only way to assert exact texts or stored values.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely useful context beyond them: the manage_automation requirement, the returned binding (productBindingId of the TRIBUTE Payment block), that a purchase runs the Paid branch, and the TRIBUTE_IMMUTABLE_BENEFIT rule that published benefits are frozen while messages stay editable. That immutability disclosure is exactly the kind of consequence the annotations cannot express; only the interaction between destructive writes and saved messages is left implicit.

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

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

Front-loaded with the primary action, then prerequisites, return value, and the immutability caveat in a logical order with no filler. Some sentences are dense run-ons (the Paid-branch/variable sentence), but nothing is redundant enough to cut.

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

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

There is no output schema, and the description compensates by saying exactly what comes back and how the returned id is consumed. Permission requirements, upstream discovery calls, downstream purchase behavior, and the immutability/editability split are all covered, which is sufficient for a 4-parameter mutation tool of this 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?

Schema coverage is 100% and each parameter is already well documented, so the baseline is 3. The description adds cross-parameter meaning the schema does not carry on its own — that the productId ties to a Payment block's productBindingId, that the variable top-up is optional and must not duplicate the Paid branch's own addition, and that the product must be approved and come from list_tribute_account_products.

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

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

Names a specific verb and resource (set up / change a Tribute product for sale in this application) and immediately distinguishes the create-vs-update path with 'one saved product per Tribute product, so calling it again updates', which tells the agent there is no separate update sibling. That is a precise, unambiguous 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?

States the prerequisite ('Requires manage_automation') and clarifies that re-invocation is the update path, so the agent knows not to hunt for an update variant. It stops short of naming explicit alternatives or when-not-to-use conditions (e.g., when to call update_tribute_connection instead), which keeps it below 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, openWorldHint=false, and destructiveHint=false, but the description adds meaningful traits: no API key required, summaries only with no flow body, no-arg behavior returns top examples, and empty results instead of errors. These are useful behavioral disclosures 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?

The description is a dense but front-loaded paragraph that leads with the action and resource before covering return shape and edge cases. Every sentence contributes, though it could be slightly tighter by separating the return-field list from the main flow.

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 returned summary fields (id, title, summary, useWhen, tags, requiredModules, hasSchemaExample) and explaining that full bodies require get_flow_example. Combined with the read-only annotations, an agent has enough to call this correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents tags, limit, and query semantics. The description adds only the high-level no-argument behavior and the empty-list edge case, which is consistent with the baseline when the schema carries the parameter detail.

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

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

States a specific verb and resource ("Search the library of reusable flow examples") and scopes it with the business cases it covers. It also distinguishes itself from get_flow_example by explaining that this tool returns summaries only and that an id is needed for the full example.

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

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

Gives clear routing to the sibling get_flow_example for full bodies, and explains the no-argument browse behavior and the empty-list case for unmatched queries. It does not explicitly compare against other search tools like search_flows, so it is not a full when/when-not statement, but the primary alternative is named.

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

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

Annotations already cover the safety profile, so this is beyond the bar: the description explains the undocumented variable-name matching behavior, names each truncation cause (FLOW_LIMIT, ROW_LIMIT, MATCHED_VARIABLES, MATCHES_PER_FLOW, MATCHES_PER_BLOCK) and what it means for completeness, and warns that a truncated answer is not proof of absence before a rename/delete.

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

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

Purpose and routing are front-loaded in the first two sentences, and the truncation catalogue is genuinely load-bearing for interpreting results. It is still long, and the sentence about `truncated`/`cappedBy` restates material already present in the `limit` schema description, which is the main 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?

With no output schema, the description carries return-value semantics itself — truncated, cappedBy, matchCount, the 12/3 match caps, the 1000-row ceiling, and the 25-variable resolution cap — plus scope exclusions. An agent has everything needed to call it and to judge result 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 the baseline is 3; the description adds real meaning about the query parameter by explaining that variable-name matches resolve to referencing blocks and that truncated/cappedBy interplay means limit is only one of several cutting limits. That said, much of the limit/truncation text duplicates what the schema's own `limit` description already says.

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

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

States a specific verb and resource ('Find every flow and block whose contents contain a keyword') and immediately scopes it ('read-only'). It also enumerates exactly what surfaces are searched and explicitly names the sibling it replaces (get_flow_context) and the ones it defers to (list_broadcasts, operations 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?

Gives an explicit routing rule: '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 (broadcast-backed flows, operation graphs) and points to the alternatives for those cases.

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

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

Annotations already flag destructive/non-idempotent/open-world, and the description goes well beyond them: per-contact isolated dispatch with per-row `ok:false`/`error`/`refused` codes, refusal rules for unsubscribed contacts and inactive bots, sleeping bots being woken, no deploy needed, the required send_flow_to_contact permission, and the explicit warning never to blind-retry a timeout. The 'not reversible / cannot be recalled' line partly restates destructiveHint but adds the concrete consequence.

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

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

Front-loaded with the core purpose and the send_message alternative in the first sentences, and nearly every sentence carries operational information. It is dense, though: the refusal rule is stated twice (once generally, once with the `refused` enum detail) and some flow-type/limit details repeat the schema descriptions.

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

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

No output schema exists, yet the description explains the return shape (`results` rows, `sent`/`failed` counts), the auth/permission requirement, workspace resolution caveats handled by the schema, and the concurrency semantics. An agent has everything needed to call it safely and interpret 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 coverage is 100%, so the baseline is 3; the description still adds real meaning — flowId must be an already-applied interactive flow from apply_actions, contactIds are FlowCastle ids not platform ids with duplicate collapsing, and params are run-scoped {{param|id}} values where a missing required param rejects the entire call before anyone is messaged.

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 precise verb+resource+scope: run an EXISTING interactive flow for each listed contact right now, outside any trigger, starting at the start block. It explicitly distinguishes itself from send_message (custom text with buttons) and from broadcast/operation flows, so an agent can pick it correctly without opening another schema.

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

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

Gives explicit when-to-use ('when the WHOLE message is the flow'), when-not (large audience → create a broadcast; custom text → send_message with buttons; operation flow → run_operation), and flow-type exclusions (broadcast and operation flows rejected). Alternatives are named with the condition that selects them.

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

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

Far exceeds the annotations: discloses async delivery semantics, that later failures are written to flow logs under action `direct_message` rather than returned, the manage_broadcasts permission requirement, the telegram_mtproto "Sending from this account" toggle being OFF by default and unchangeable by tools, HTML escaping rules and the plain-text fallback, and the irreversibility warning. Annotations only flag destructive/non-idempotent; the description adds the operational detail an agent actually needs.

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

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

Front-loaded with purpose and the sibling alternative before dense detail. Nearly every clause carries information, but the block is very long and stacks formatting, media, buttons, delivery and account-restriction topics without clear sectioning, so it is harder to scan than it needs to be.

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, but the description covers return semantics (success means accepted, not delivered), the failure-reporting channel (query_flow_logs / get_contact_activity), permissions, channel restrictions and non-idempotency. Nothing an agent needs in order to call it safely 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 baseline is 3, but the description adds real meaning: platformId uniqueness is per-bot with the candidate-bots failure mode, botId's role, parseMode's exact token set and escaping rules, and flowId requiring an already-applied INTERACTIVE flow with broadcast/operation flows rejected. Some of this duplicates the schema wording, which keeps it below 5.

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

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

States a specific verb+resource with scope: "Send a message to ONE contact right now, outside any flow." Immediately distinguishes from the broadcast alternative and later from send_flow_to_contacts, so an agent can differentiate it from siblings without opening a schema.

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

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

Explicit routing to alternatives ("For reaching many contacts use a broadcast instead", "To send a WHOLE flow... use send_flow_to_contacts"), explicit incompatibilities ("Buttons cannot be combined with media; send those as two messages"), and explicit when-not (refused for Instagram, mail, Telegram user accounts, SDK bots). Covers precedence between contactId and platformId plus botId disambiguation.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations by explaining what destruction means (omitting an entry removes it), the permission requirement, the silent-failure mode for unjoined chats ('saved but never produces a message'), and the propagation delay ('within a few minutes, no restart'). The only thing not disclosed is the response payload, which is minor for a settings mutation, so a 4 rather than 5.

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

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

Front-loads the core action and SET semantics before the caveats, and nearly every sentence carries distinct operational information. Minor redundancy: the join requirement and its consequence are stated twice ('only joined chats can be watched' then 'saved but never produces a message'), and the empty-list rule repeats the schema description.

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

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

For a destructive three-parameter settings mutation with no output schema, the description covers permissions, list replacement behavior, entry validation, propagation, and the edge case of an empty array. Nothing an agent needs in order 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 chatId/username/mode/applicationId semantics are already documented in the schema. The description reinforces the entry format ('chatId (e.g. "-100…") or a public username/t.me link') and adds the joined constraint, but says nothing about botId or applicationId selection beyond what the schema already states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Replace a telegram_mtproto userbot's watched-groups list') plus the scope of what a group means ('the chats it monitors'), and names the sibling list_watched_groups as the read counterpart. An agent can distinguish it from list_watched_groups and from generic chat tools without opening the schema.

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

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

Explicitly instructs to call list_watched_groups first and re-send existing entries, states the prerequisite (manage_settings permission), the join requirement before adding a chat, and the counter-intuitive empty-list case ('watch every joined chat' — NOT 'watch nothing'). When-to-use, when-not, and the alternative tool are all named.

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

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

Beyond the annotations, the description discloses the send gate (OFF by default, no tool flips it, text only, no media/buttons), the permission requirement, the live-read cost (large accounts up to a minute), idempotency behavior (existing contacts untouched), and the watched-groups non-effect. These are exactly the operational traits annotations cannot express.

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

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

The purpose and the send-gate caveat are front-loaded, and every sentence carries information. It is a dense single paragraph, though, and the constraint clauses (permission, sending limits, idempotency, watched-groups) could be separated for faster scanning.

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

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

For a 4-parameter mutation with no output schema, the description covers what gets created, what is left alone, the failure conditions, and the permission/auth context. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete narrowing example (["group","channel"] to exclude personal DMs) and reiterates the single-userbot omission rule for botId. It does not add anything about limit or applicationId beyond the schema, so it exceeds baseline only modestly.

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 ('Import a telegram_mtproto userbot's existing chats as contacts') and enumerates exactly which dialog kinds are imported (DMs, groups, channels). It clearly distinguishes this bulk-import from single-record siblings like create_contact and list_contacts by describing the live dialog-list read and the idempotent 'creates missing contacts' semantics.

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

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

It states when to reach for this tool (so existing chats become contacts send_message can target without waiting for an inbound message), what it explicitly does NOT do ('Does NOT change the watched-groups list'), the prerequisite (manage_broadcasts permission, userbot connected), and the downstream constraint (sending stays rejected until the dashboard toggle is on). An agent has enough to decide for or against it.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description adds a permission requirement, the partial-update contract (omitted fields unchanged), and the return value. It does not explain what makes the call destructive (deactivation via isActive), but that is documented in the schema, so the marginal gap is small.

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

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

Four short sentences, front-loaded with purpose, followed by permission, mutation semantics, and return value. The parenthetical field list mildly duplicates the schema property names but earns its place as a quick 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?

Covers purpose, permission, partial-update behavior, and return value; annotations and the 100%-covered schema carry the rest (per-param details, destructive semantics of deactivation). No output schema exists, but the description states what is returned, which is sufficient.

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

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

Schema description coverage is 100%, so all seven parameters are fully documented in the schema, including the EXECUTE_FLOW side effect and language normalization rules. The description only names the settings at a high level and adds no per-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?

States a specific verb (update) and resource (application-level settings) and enumerates the concrete settings covered. An agent can distinguish this from create_application/deploy_application without opening either schema.

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

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

Gives a clear precondition (the manage_settings permission in that application), which tells the agent when the call will succeed. It does not, however, name an alternative for creating or deploying applications, so routing guidance is context-only rather than explicit.

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