Kite

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

Annotations already establish that this is a non-read-only, non-destructive, closed-world mutation. The description adds behavioral context beyond annotations by noting optional flow edits, subcommand naming, and Discord propagation latency ('within a minute'). It omits auth and duplicate-name behavior, but adds meaningful context for an annotated mutation.

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

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

The description is three short sentences and is front-loaded with the core action. Every sentence contributes useful information: core creation, subcommand naming, or visibility latency.

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

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

Given a rich schema and annotations covering safety, the description is largely complete for a creation tool: it covers the core action, optional flow edits, subcommand naming, and propagation delay. It could do more to explain when to choose create_command over edit_flow and what errors or duplicate names mean.

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 carries most parameter detail. The description still adds value by explaining that subcommands are named like 'mod ban' and that edits build the command's flow, extending the meaning of the name and edits 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 uses a concrete verb and resource: 'Creates a slash command', and clarifies subcommand naming behavior. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as edit_flow or get_command.

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

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

The description does not say when to use create_command instead of edit_flow, get_command, list_commands, or other command-management tools. The subcommand naming note is useful context, but there is no explicit guidance on choosing this tool versus alternatives.

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

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

Annotations already establish that this is a non-read-only, non-destructive, closed-world creation, so the description's job is to add operational context — and it does, by calling out the Discord intents, permissions, and channel setups each event requires. It doesn't discuss return value, whether edits are atomic, or failure/rollback behavior, which keeps 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?

The purpose statement is front-loaded and the bullets are individually short and scannable. A few entries (guild_boost, guild_audit_log_entry_create) run to three sentences of setup detail that could be tightened, but every line carries information otherwise absent from 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?

Coverage of trigger types is thorough, but the `edits` parameter — a complex oneOf of add/update/remove/connect/disconnect operations — gets only "optionally with edits that build its flow," and there is no output schema or statement about what the call returns (e.g., the new listener's ID). For a creation tool with a nested graph-editing parameter, that is a meaningful gap.

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

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

The schema covers 83% of parameters, so the baseline is 3; the description earns above that by explaining what each event_type value means, which the bare enum does not. It adds nothing for cron, webhook, enabled, or app_id (all schema-documented) and only alludes to `edits` in a single clause.

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 and resource ("Creates an event listener") plus the scope of optional flow edits, then enumerates every supported trigger. An agent can distinguish this from delete_event_listener / get_event_listener / edit_flow 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?

The per-event bullets effectively say when a given trigger fires (including prerequisites like the Server Members Intent, View Audit Log permission, and boost system-message channel), which is useful selection context. However, there is no guidance on when to use this tool versus edit_flow or create_command — e.g., whether pre-building a flow here is preferred over creating then calling edit_flow — so the routing is only implied.

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

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

The annotations already establish that this is a non-read-only, non-destructive, closed-world create operation. The description adds a non-obvious behavioral detail: buttons and select menus receive a flow_source_id, which is important for wiring them later with edit_flow.

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

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

The description is two short sentences with no wasted text, and the core purpose is front-loaded. The follow-up sentence adds useful integration context without excessive length.

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

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

For a create tool with annotations but no output schema, the description covers purpose and one key behavioral side effect. It is still thin on parameter requirements and does not explain return behavior, template limits, or validation expectations.

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%, and the description does not explain the required name, description, or app_id parameters beyond the schema's brief hints. The mention of buttons and select menus loosely relates to the nested data object but adds little concrete parameter guidance.

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

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

The description gives a specific verb and resource: creating a message template that flows can send. This distinguishes it from plain message operations, though it does not explicitly contrast with update_message or get_template.

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 phrase 'which flows can send' implies the tool is used when building flow-sent messages, and the edit_flow reference gives follow-up context. However, there is no explicit when-to-use guidance or comparison with sibling tools such as update_message or create_command.

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 is a non-read-only, non-destructive, closed-world operation. The description adds useful behavioral context by explaining that the variable keeps a value between runs, but it omits duplicate-name behavior, required permissions, and what the creation returns.

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 definition is a single front-loaded sentence with no wasted wording. It conveys the action, persistence semantics, and target context efficiently.

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

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

For a simple three-parameter create tool with annotations and partial schema descriptions, the description covers the essential purpose and persistence behavior. It still leaves gaps around return behavior, duplicate handling, and relationship to list_variables, so it is adequate rather than complete.

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

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

The schema documents app_id and scoped, covering two of the three required parameters, while name is self-evident. The description does not add parameter-level meaning, but with 67% schema coverage the schema already carries most of the burden.

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 ('Creates a stored variable') and explains the core concept of persistence between runs. It does not explicitly distinguish this from the sibling list_variables tool, but the create action is clear.

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

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

It states the usage context ('for blocks with a variable_id setting'), which implies when the tool is relevant. However, it does not mention alternatives such as list_variables for inspecting existing variables, nor does it give any when-not-to-use guidance.

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

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

annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows mutability and risk without the description. The description adds only an intent guard, not the details that matter for a destructive call: irreversibility, whether attached event listeners or triggers are cascaded, or permission requirements. With annotations carrying the safety profile, a 3 is fair, but these gaps are meaningful for a 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?

Two short sentences, the action stated first and the guard second, with zero filler. Nothing is redundant or buried.

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, no-output-schema tool in a family of parallel delete_* siblings, the description omits cascade behavior, irreversibility, whether listeners bound to the command are removed, and how to confirm the right command_id. The single intent guard does not cover what an agent needs before running a delete.

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 exactly 50%: app_id points to list_apps, but command_id has no description anywhere. The description says nothing about either parameter, so the undocumented half is not compensated for and an agent gets no hint on how to obtain or validate command_id.

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

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

"Deletes a command" names a specific verb and resource, so the purpose is unambiguous, but it is essentially the tool name and title restated with no added scope. It never distinguishes this from delete_event_listener or delete_message beyond the noun.

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?

"Only do this when the user asked for it" supplies a real use condition and implies a caution against proactive deletion, which is more than nothing. It names no alternative (e.g., set_enabled to disable, or get_command to confirm the target), so an agent still has to infer the safer path.

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 readOnlyHint=false, so the safety profile is covered structurally. The description adds the extra behavioral constraint that user consent is required, which is genuinely beyond the annotations, but it never says what is lost, whether the deletion is reversible, or whether the listener can be recreated via create_event_listener.

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

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

Two short sentences with the action first and the guardrail second — no padding and nothing buried. The terse size is appropriate, though the grammar slip ("a event") and the absence of any confirming detail slightly under-deliver on the second sentence's value.

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

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

For a destructive, no-output-schema tool with an undocumented required ID, the description should at minimum say how to discover the event_listener_id and what state the app is left in. It provides neither, leaving the agent to infer discovery flow and irreversibility entirely from the schema and annotations.

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%: app_id is documented as coming from list_apps, but event_listener_id has no description anywhere. The description mentions neither parameter, so it does nothing to compensate for the undocumented identifier or explain its relationship to list_event_listeners.

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 (deletes) and resource (event listener), which is unambiguous against siblings like delete_command or delete_message by name alone. However, it offers no explicit differentiation or any hint of what an event listener is in this system, so it earns a solid but not top score.

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?

"Only do this when the user asked for it" is a real guardrail that implies when-not-to-use (never autonomously), which is more than most mutation tools give. But it names no alternative (e.g., set_enabled to disable instead of delete) and doesn't clarify how explicit confirmation must be.

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 destructiveHint=true and readOnlyHint=false, so the description does not need to prove this is destructive. It reinforces deletion and adds a user-request-only caution, but it does not disclose irreversibility, permission requirements, or what exactly will be removed.

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

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

The description is two short sentences with zero waste. The core action is front-loaded, followed by a concise usage warning.

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 two-parameter mutation with no output schema, the description establishes the action and a basic safety guardrail. It remains incomplete because it does not explain the message_id parameter, whether deletion is permanent, or what side effects to expect.

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 only 50%: app_id is documented as coming from list_apps, but message_id has no schema description. The tool description mentions no parameters and does not compensate by explaining that message_id is the template identifier.

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: 'Deletes a message template.' This distinguishes it from sibling delete_command and delete_event_listener. However, the tool name 'delete_message' could suggest deleting messages rather than templates, and the description does not explicitly clarify that distinction against message-oriented siblings like update_message or list_messages.

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?

'Only do this when the user asked for it' provides a clear guardrail for a destructive operation. It does not mention alternatives such as updating or disabling the template, nor does it specify conditions under which deletion should be avoided beyond requiring user intent.

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 destructiveHint and openWorldHint, yet the description adds substantial context: bot role permissions constrain what can succeed, changes are immediate and irreversible, and every write is recorded in the app logs and server audit log. It also documents a non-obvious truncation contract with the {"truncated": true, "result": ...} shape and warns never to send a truncated list or string back to Discord because omitted items would be deleted.

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

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

Purpose is front-loaded in the first sentence, and nearly every later sentence carries load-bearing information about truncation or irreversibility. The truncation/round-trip warning runs long and could be tightened, 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?

For a six-parameter open-world passthrough with no output schema and no enums, the description covers discovery (search first), permissions, irreversibility, audit logging, and the exact shape and handling of truncated responses. An agent has everything needed to call it safely without guessing at return semantics.

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 app_id, operation, path_params, query, body and reason are all documented in the schema. The description adds only marginal guidance beyond that, hinting that limit and pagination query parameters are the way to retrieve data omitted by truncation.

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: sends a request to a Discord API endpoint using an app's bot token and returns the JSON. It is clearly the generic passthrough among siblings that otherwise expose narrow operations like create_message or list_channels, and it names search_discord_api as the endpoint-discovery 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?

Explicitly says to find the endpoint with search_discord_api first and to make only the changes the user asked for, which gives a clear workflow precondition and a scope limit. It does not say when to prefer a dedicated sibling tool (e.g. create_message) over this generic request, which is the one routing decision 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?

Adds real behavioral context beyond the annotations: the edit is atomic — "If an edit or the resulting flow has problems, nothing is saved and the problems are returned" — which tells the agent failures are non-partial and surfaced as a problem list. The annotations already flag destructiveHint, so the remaining gap is only around what else gets touched (e.g. whether prior flow state is replaced).

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: purpose first, target selection second, failure behavior last. Every sentence carries information an agent needs and nothing is repeated from 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 6-parameter tool with a nested oneOf edit vocabulary, no output schema, and destructive semantics, the atomicity note is good but there is no pointer to get_flow_guide/get_blocks for discovering block types and refs, and no hint about what the returned problem list looks like — gaps an agent will hit on first call.

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

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

Schema coverage is only 50%, and the description compensates by declaring the target selector as a one-of across command_id/event_listener_id/message_id, a constraint the schema does not encode. It still says nothing about edits op semantics or flow_source_id, so the compensation is partial.

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

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

States a specific verb (edits/saves) and resource (the flow), and enumerates the three target kinds: command, event listener, message component. That distinguishes it well from the create_*/delete_* siblings, though it never names a sibling (e.g. get_flow_guide or create_command) to anchor the distinction.

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

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

"Pass one of command_id, event_listener_id or message_id" tells the agent how to select a target, which is genuine usage guidance, but there is no statement of when to use this versus create_command/update_message, nor any prerequisite such as needing a flow guide or existing flow.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the substantive detail that each entry includes behavioral info, usage locations, outputs, and settings/result schemas. It omits edge-case behavior such as unknown type names or the 30-item cap's consequences.

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 purpose, and the second sentence adds a non-redundant batching instruction. 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 correctly spends its words describing the return payload, which is the main thing an agent needs. Minor gap: no acknowledgment of the 30-type maximum or failure modes for invalid type names.

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 'types' array is documented with an example value, so the schema carries the load. The description only reinforces plurality ('all the types you need') and adds no format or naming guidance beyond the schema.

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

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

States a specific verb and resource ('Gets block types') and enumerates exactly what is returned: behavior, allowed locations, outputs, and the JSON Schemas of settings and result. That is far more informative than the sibling list_* tools, though it does not contrast itself with search_blocks, which is the nearest alternative an agent must choose between.

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?

'Get all the types you need in one call' implies batching rather than one type at a time, which is useful steering. However, there is no explicit guidance on when to use this versus search_blocks, or what happens if a requested type does not exist.

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 safety profile is covered. The description adds one genuinely non-obvious fact — the returned command comes bundled with its flow — which matters given there is no output schema, but it says nothing about not-found/error behavior for a closed-world ID lookup.

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?

A single twelve-word sentence with the resource and scope front-loaded; nothing is padded or restated.

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

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

For a two-parameter, read-only getter this is close to sufficient, but with no output schema the description should say more about what 'flow' contains and what happens when the ID is invalid. As written, an agent knows what it fetches but not what it gets back in any detail.

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 both parameters are documented there (app_id even points at list_apps). The description adds no elaboration on parameter meaning, so the baseline 3 for fully covered schemas 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?

Clear verb+resource: 'Gets a slash command of an app' names the entity and its owner scope, and 'with its flow' hints at the payload shape. It does not explicitly distinguish itself from list_commands or get_flow_guide, so sibling differentiation is left implicit.

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?

Usage is only implied: fetching a single command by ID presupposes you already have app_id and command_id, but the description never says to obtain them from list_apps/list_commands (only the schema mentions list_apps) or when to prefer this over list_commands. No exclusions or prerequisites are stated.

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 safety profile is covered. The description adds almost nothing beyond that: it doesn't say what happens when the ID doesn't exist, whether the flow is returned inline or as a reference, or what the response payload looks like—despite read-only get tools living or dying on their return shape.

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?

A single nine-word sentence with no filler and the resource stated up front. It is efficient, though efficiency here reflects under-specification rather than disciplined editing.

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

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

For a two-parameter read with full schema coverage and no output schema, the essentials for invoking it are present. The gap is that the description promises the flow but never characterizes the returned data, and an agent cannot infer the response shape from an absent output schema.

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

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

Schema description coverage is 100% (app_id documented as coming from list_apps, event_listener_id self-evident), so the baseline is 3. The description's "of an app" mildly echoes app_id but adds no format, source, or enumeration detail 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?

Specific verb+resource ("Gets an event listener") plus the scoping detail "of an app" and an indication that the related flow is included. It is distinguishable from siblings like get_command or get_message by resource name, though the phrase "with its flow" stays somewhat ambiguous about whether the flow is embedded or merely referenced.

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?

No guidance on when to use this rather than list_event_listeners (to discover IDs) or get_flow_guide, and no statement of prerequisites or error conditions. Usage is only inferable from the tool name and the schema note that app_id comes from list_apps.

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 safety is covered. The description adds useful context about the guide's content scope and the 'call once' behavior, though it does not describe the form of the returned guidance material.

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: the first defines content scope and the second gives the usage rule. Purpose is front-loaded and the call-frequency instruction follows directly.

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

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

For a zero-parameter, read-only guide tool with no output schema, the description supplies everything needed: what it explains, when to invoke it, and how often. 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?

The tool takes no parameters, so there are no parameter semantics to explain. The baseline for zero-parameter tools is a 4.

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 ('Explains') and a clearly bounded resource (how to build flows), then enumerates the covered topics: edits, buttons, select menus, templates, placeholders and rules. This distinguishes it from sibling tools like edit_flow or get_blocks, which perform actions rather than explain concepts.

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

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

It explicitly states the trigger: 'Call it once before creating or editing a flow.' That is clear when-to-use guidance, including a one-time constraint. It does not name an alternative or exclusion, but no obvious competing guide tool exists among the siblings, so this is strong but not exhaustive.

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 safety is covered. The description adds real value by naming the returned payload (content, per-component flow), but it omits error behavior for unknown IDs and says nothing about the shape or size of the response, which matters since there is 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?

A single front-loaded sentence with no filler. The trailing clause about flow_source_id is dense but does convey per-component detail rather than padding.

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

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

For a two-parameter read-only lookup with full schema coverage and no output schema, the description covers what is fetched well enough to call it correctly. It falls short only on failure modes and the ambiguity between this tool and get_template.

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 documented and the baseline is 3. The only added semantic is "by its flow_source_id", which itself is unexplained jargon; the description does not clarify identifier formats or where message_id comes from (the way app_id is sourced from list_apps).

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 ("Gets a message template") and enumerates what is returned: content plus the flow behind each button and select menu. It is clear what the tool fetches, though it does not distinguish itself from siblings like get_template or get_message's counterpart list_messages, which an agent could easily confuse.

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?

There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives such as list_messages or get_template. The agent must infer that this is the fetch-by-ID counterpart to list_messages purely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the meaningful behavioral distinction that supplying app_id broadens the response to include the app's current install state and a diff of what an update would change, which an agent could not infer 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?

Two short sentences, front-loaded with the core action before the optional-parameter modifier. The phrasing is dense and comma-heavy but every clause adds information; nothing is padding.

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

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

With no output schema, the description must convey return content, and it does so concretely: installable parameters, integrations, and the app-scoped comparison. A minor gap is that it never says what a bare call without app_id returns beyond the base template details, but for a two-parameter read tool this is close to complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantic effect of app_id (returns existing app state plus prospective update changes) rather than just restating its type. template_id gets no additional narrative beyond the schema pointer, which keeps it from 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?

The description states a specific verb and resource and, unusually, also enumerates what the returned template object contains (parameters to fill in, required integrations), which distinguishes it from a bare 'get'. It doesn't explicitly name the contrasting siblings search_templates or install_template, so it falls short of a 5.

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

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

The conditional 'With app_id, also...' implies when to supply the optional parameter, which is useful routing. However, nothing states when to use this versus search_templates or install_template, and the pre-install inspection workflow is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: credits reset at the start of each month in UTC and the app stops running flows when credits are exhausted, which an agent wouldn't know from 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?

Two dense sentences, front-loaded with the returned data followed by reset mechanics and cross-references. Every clause earns its place, though the parenthetical breakdown is slightly lengthy.

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

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

No output schema exists, but the description compensates by enumerating the returned data (monthly usage, plan allowance, daily and per-category breakdown). Combined with 100% param coverage and read-only annotations, an agent has nearly everything needed, with only exact response shape left implicit.

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

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

Schema coverage is 100% and app_id is documented in the schema as coming from list_apps. The description refers to 'an app' but adds no format or source detail beyond the schema, 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 (Gets) and resource (credits an app used this month) plus the returned fields: plan allowance, daily usage, and breakdown by commands, event listeners, and messages. Clearly distinguishable from siblings like list_plans and get_blocks, which are explicitly named for different concerns.

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?

Implies the usage context (checking credit consumption and plan limits) but never explicitly states when to call this versus alternatives. The referenced siblings get_blocks and list_plans are for cost-per-block and plan contents, not alternative ways to get usage, so no true routing guidance is given.

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 non-read-only, non-destructive, non-open-world, and the description adds real behavioral context beyond them: messages are posted to the channel immediately (an observable side effect) and third-party templates require user confirmation. It stops short of describing failure behavior or return values, so not 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 sentences, each carrying distinct information: what is added, the message side effect, the third-party confirmation rule, and the prerequisite lookup steps. Front-loaded with purpose; only minor tightening would be possible.

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

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

For a mutation tool with 6 params (nested objects), rich annotations, and no output schema, the description covers prerequisites, sourcing of parameter values, side effects and a confirmation gate. It does not say what the call returns or how partial failures behave, which is the only remaining gap.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description goes further by explaining that parameters (channels/roles) must be sourced from list_channels and list_roles or asked of the user, which adds operational meaning to the parameters object. The items/messages/server_id interplay is left to the schema.

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

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

States a specific verb ('Adds') and resource ('a template to an app') and enumerates exactly what gets installed: commands, event listeners, messages and stored variables. This clearly distinguishes it from the sibling get_template / search_templates / update_template_install read and edit 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 prerequisite workflow (get the template with get_template and app_id first), tells the agent to ask the user for parameters it can't resolve, and names list_channels and list_roles as the sources for pickable values. It also states a when-not/gating rule: confirm with the user before adding templates not made by Kite.

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 safety profile is covered. The description adds a useful scoping detail – these are the calling user's own apps, not other users' – but says nothing about volume, ordering, or pagination of the result.

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?

A single short sentence with no filler, and the resource definition is front-loaded. Nothing could be removed without losing meaning.

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

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

For a zero-parameter read tool with annotations covering safety, this is close to sufficient, but with no output schema the description could have said what an app record contains or how many are returned. That gap is minor but real.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies no input is needed.

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 ("Lists the apps") and disambiguates the term by defining apps as "the Discord bots they build." That distinguishes it from sibling listers like list_servers and list_commands, though it doesn't explicitly say how it relates to them.

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

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

No guidance on when to call this versus alternatives such as list_servers or get_blocks, and no prerequisites or exclusions. The agent must infer usage purely from the name and the one-line definition.

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 safety profile is covered. The description adds the useful scope constraint that only channels visible to the app's bot are returned, but says nothing about ordering, pagination, or what fields come back.

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

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

Two short sentences, front-loaded with the purpose, which is good. But the second sentence spends its entire budget on a parameter the tool does not accept, so it does not earn its place.

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

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

For a simple two-parameter read tool with a 100% documented schema and safe annotations, most of what an agent needs is present. Missing: confirmation that results are read-only server-scoped data with no pagination, and there is no output schema to explain the returned channel objects.

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 app_id and server_id are already fully documented. However, the description explains a "type" parameter (0 for text, 4 for categories) that does not exist in the input schema, which can mislead an agent into passing an unsupported argument.

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 ("Lists the channels of a Discord server") and scopes it to servers the app's bot is in, which distinguishes it from siblings like list_roles and list_servers. It does not explicitly contrast itself with any alternative, but the resource is unambiguous.

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

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

There is no guidance on when to use this versus alternatives such as discord_api_request or list_servers, and no stated prerequisites (e.g., the bot needing the right intents/permissions to see channels). The only implied condition is that the bot must be in the server, which is stated as scope rather than usage advice.

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 safety is covered. The description adds genuinely non-obvious behavior: flows are excluded from the response and each subcommand (e.g. /mod ban) is a separate command with its own flow, which affects how results must be interpreted.

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

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

Two short sentences with no waste; the output-scope constraint is front-loaded and the granularity note follows as supporting detail.

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

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

The description covers what is returned and how commands are structured, which matters since no output schema exists. It omits anything about ordering or result size/pagination, a minor gap for a list tool.

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

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

Only one parameter, and the schema documents it fully ('The ID of the app, from list_apps'). The description adds nothing about app_id beyond that, 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 and resource ('Lists the slash commands of an app') with a clear scope qualifier ('without their flows'). An agent can distinguish it from get_command (singular retrieval) and from list_apps, 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 phrase 'without their flows' implicitly tells the agent to look elsewhere (e.g. get_flow / edit_flow) when flow data is needed, but no alternative tool or condition is named. Usage is inferable rather than stated.

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 safety profile is covered. The description contributes useful domain context about what event listeners are (Discord events, schedules, webhook requests), but says nothing about return format, pagination, or ordering.

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

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

Two short sentences, zero waste, and the key distinction ('without their flows') is front-loaded in the first sentence. The second sentence adds clarifying domain context without padding.

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

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

For a simple annotated read-only list tool with full schema coverage and one obvious parameter, the description covers what it is and what it excludes. Only return-shape and pagination details are absent, which is acceptable given the readOnly annotation and the tool's simplicity.

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

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

There is a single parameter with 100% schema description coverage, including the useful hint that app_id comes from list_apps. The description adds no additional parameter 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 ('Lists the event listeners of an app') and adds a scope qualifier ('without their flows') that distinguishes it from get_event_listener. It does not explicitly name the sibling to route away from, but the intent is unambiguous.

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

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

Usage is only implied: the 'without their flows' clause hints that get_event_listener should be used when flows are needed, but no explicit when/when-not statement or alternative is named. An agent can infer the list-vs-get split from the sibling names, but the description doesn't do that work.

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 safety is covered. The description adds useful behavior (results are the NEWEST entries, filters are optional), but says nothing about result volume, pagination, or how far back the log window goes — relevant for a log listing.

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?

One sentence, front-loaded with the verb and resource, with the optional filter behavior trailing. Slightly awkward phrasing ('like errors of flows') but no wasted text.

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

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

With no output schema and 5 parameters, the description covers what the tool returns conceptually (log entries) and the filters, but omits anything about ordering guarantees beyond 'newest', result size, or log retention — gaps an agent would want before relying on 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 only 40%; command_id, message_id, and event_listener_id have no schema descriptions. The description gives those three parameters meaning as narrowing filters (one command, event listener, or message template), which is real added value; only limit and app_id are left to the schema.

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

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

States a specific verb and resource ('Lists the newest log entries of an app') and adds scope detail ('like errors of flows'). It is clearly distinguishable from get_command/list_commands siblings, though it doesn't name any sibling 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 phrase 'like errors of flows' implies the debugging use case, and 'optionally only those of one command...' implies filter narrowing, but there is no explicit when-to-use/when-not guidance or pointer to an alternative tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds conceptual context about template components running flows, but says nothing about return shape, ordering, or pagination for a list operation. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Two short sentences with the core action front-loaded. The second sentence is useful domain framing but slightly tangential to the mechanics of invoking this specific 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?

For a simple read-only list tool with one fully documented required parameter and no output schema, the definition covers what it returns at a conceptual level. Only return ordering and pagination behavior are absent, which is a minor gap.

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

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

There is a single parameter with 100% schema description coverage, and the schema already tells the agent to get the ID from list_apps. The description adds no additional meaning about the app_id beyond what the schema provides, 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 states a specific verb (Lists) and resource (message templates), scoped to an app, which separates it from siblings such as get_message, create_message, and list_commands by name and scope. It does not explicitly contrast against those siblings in prose, keeping it just short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives like get_message for a single template. The second sentence implies the domain context (flows send these templates, and their components trigger flows), which lets an agent infer relevance but not the selection logic.

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 (readOnlyHint=true, openWorldHint=false), and the description adds real value by describing the shape of the response – currency, quota limits, and the URL where the plan can be changed. It does not discuss ordering, pagination, or whether all plans or only the current one are returned, 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?

Two sentences, front-loaded with what the tool returns and followed by the interaction policy. Both sentences carry weight, though the second one's example ('a smaller AI model tier') is slightly more than strictly needed.

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 one-parameter read tool with annotations covering safety and no output schema, the description supplies the missing piece – what the response contains. Nothing critical for correct invocation is absent, though a note on which plans are returned would round it out.

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 single app_id parameter is already documented as coming from list_apps. The description adds no further semantics about the 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 ('Lists Kite's plans') and enumerates what comes back: prices in USD, limits such as credits per month, and the plan-change page. That is enough to separate it from neighbours like get_usage or list_apps, 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?

Gives a clear trigger ('when the app is near a limit or the user asks') and an explicit pre-step ('first suggest ways to need less, like a smaller AI model tier'). It stops short of naming the alternative tool to consult (e.g. get_usage) for checking limits, so the routing is implied rather than fully explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds two real behavioral facts beyond that: ordering (highest first) and the existence of managed roles owned by bots/integrations. However, it never says whether managed roles are included in the results or filtered out, which is exactly the ambiguity the second sentence raises.

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 compact sentences with the core operation and ordering front-loaded, no filler. The second sentence is terse to the point of being ambiguous, which slightly undercuts its value.

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

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

Two fully documented required parameters and annotation-covered safety mean little is missing. But with no output schema, the description should at least hint at what a role entry looks like, and it should resolve whether managed roles appear in the list rather than just noting they exist.

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 both parameters are documented with their provenance (from list_apps / list_servers). The description adds no parameter-level meaning, 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?

Specific verb + resource ("Lists the roles") with a scope qualifier ("of a Discord server the app's bot is in") and an ordering guarantee ("highest first"). No sibling also lists roles, so differentiation is implicit, but an agent can immediately tell what this returns.

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 never says when to reach for this tool versus alternatives (e.g. discord_api_request or search_discord_api), nor any preconditions such as the bot needing to be in the server. Usage is only inferable from the verb itself.

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 safety is covered. The description contributes the meaningful nuance that only servers the bot has actually joined are returned, but says nothing about ordering, pagination, or result shape.

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?

A single sentence with zero filler, front-loading the verb and the scope qualifier. Nothing is redundant relative to the name or title.

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?

This is a simple read tool whose annotations cover its safety profile, but with no output schema the description should say what a 'server' entry contains (id, name) so an agent knows what it can feed downstream. That gap is the main incompleteness for an otherwise minimal tool.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema itself explaining 'from list_apps.' The description adds no additional meaning about app_id, 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 ('Lists the Discord servers') and adds the scope qualifier 'the app's bot is in,' which distinguishes servers from channels or roles. It never names a sibling explicitly, so an agent must infer the routing from resource nouns alone.

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?

Usage is only implied: an agent can deduce this is the way to enumerate servers for an app, and the schema points to list_apps for the ID. There is no stated when-to-use, when-not, or alternative (e.g. list_channels for per-server detail).

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 safety is covered. The description adds useful semantics — persistence across runs and per-scope values — but says nothing about pagination, volume, or what a returned entry contains.

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

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

Two short sentences with zero filler; the operation and its scope are front-loaded. The second sentence earns its place by clarifying what 'scoped' variables mean in the returned data.

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 one parameter and no output schema, the description should sketch what a listed variable looks like (name, value, scope) since the agent cannot inspect a return schema. Persistence semantics are covered, but the response shape remains unspecified.

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

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

Schema coverage is 100% and the single required app_id is documented with a pointer to list_apps, so the schema does the heavy lifting. The description only echoes that variables belong to an app, adding no format or sourcing 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 ("Lists the stored variables of an app") and adds a definition of what a variable is, which is more than a restatement of the name. It does not distinguish itself from siblings like create_variable or list_apps, so an agent must infer the read-only enumeration role.

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

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

There is no statement of when to call this versus alternatives (e.g. create_variable to add one, or where to find app_id beyond the schema). The 'keep values between runs' note is conceptual background, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: queryless calls degrade to a full title-only listing, which tells the agent what to expect from an empty search. It omits pagination and result-count 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 short sentences, zero filler, with the search behavior front-loaded and the degenerate case immediately after. 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?

For a read-only, two-optional-parameter search tool with no output schema, the description covers the search semantics and the empty-query case, so an agent can call it correctly. Only the return shape (fields per result) and result limits are left implicit.

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

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

Schema coverage is already 100%, so the baseline is 3. The description goes beyond it by stating which fields the query string is matched against (type, title, description) and what happens when query is absent, adding real semantics the schema does not carry.

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 (searches) and a specific resource (block types flows are built from), plus the match fields (type, title, description). It is clearly distinct from search_discord_api and search_templates by naming the block-type domain, though it never names a sibling directly.

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 second sentence establishes the no-argument behavior (list everything by title only), which implicitly tells an agent that omitting query is valid. However, it gives no guidance on when to use this versus get_blocks or the other search tools in the sibling set.

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 safety is covered. The description adds real value beyond that: it discloses that the searchable corpus is Discord's OpenAPI spec and that matches are operation IDs, telling the agent this is a static index lookup, not a live API call. It does not describe result shape or match ranking, so not 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?

Two sentences, no filler. The primary purpose and sibling linkage come first, and the follow-up sentence on operation IDs and examples directly supports correct invocation and correct downstream use.

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 one-parameter discovery tool with no output schema, this covers what to search, what the results represent, and which tool consumes them. The only gap is how results are shaped and ordered, which an agent can discover from the first call.

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

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

The single query parameter has 0% schema coverage, so the description carries the burden and does well: it explains the query is matched against endpoint names or paths as words, with two concrete example queries. It does not specify matching rules (word intersection vs. substring) or result limits, leaving some ambiguity about how strict the matching is.

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

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

Specific verb ("Finds") plus specific resource ("endpoints of the Discord API"), and it explicitly anchors itself to the sibling that consumes its results: "that discord_api_request can call." It also clarifies what the names actually are (OpenAPI operation IDs), which an agent could not infer from the name alone.

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 relationship to discord_api_request makes the use case clear: search here to discover an endpoint, then call it via that sibling. Example queries ("member role", "channels messages") demonstrate the expected input style. It stops short of an explicit when-not rule (e.g., don't use for listing servers/channels, which siblings cover), so it's clear context rather than 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful scope (marketplace by Kite/users plus the user's own) and empty-query behavior, though it says nothing about pagination or result 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 scope, and the empty-query behavior is stated compactly. The explanatory clause about what a template adds is mildly redundant but useful context, not filler.

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

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

For a simple read-only search with one optional parameter, the description covers the search corpus and the empty-query case. With annotations present and no output schema, the remaining gap around result shape is minor.

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

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

Schema coverage is 100%, so the single query param is already documented. The description adds semantics beyond the schema by explaining that omitting the query lists all templates.

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 (Searches) and resource (templates) and names the corpus: marketplace templates by Kite or users plus the user's own. This distinguishes it from get_template (single fetch) and install_template 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?

Explicitly says that without words it lists all of them, giving a clear use case for the optional query. It does not, however, name alternatives such as get_template for fetching a specific template or install_template for installation.

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

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

With annotations declaring destructiveHint=true and idempotentHint=true, the description adds a meaningful behavioral rule: a single call must target one resource via one ID, not both. It still omits what disabling actually does at runtime (does the command stop responding? is it reversible?) and what permissions are needed.

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, and the operation is front-loaded before the parameter constraint.

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-param toggle with annotations already covering safety/idempotency and no output schema, the description covers the essential ambiguity (which ID to pass). A sentence on the effect of disabling would make it fully complete, but nothing critical for calling it 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 25% (only app_id is documented). The description compensates for the key gap by explaining that exactly one of command_id or event_listener_id should be supplied, which the schema does not express. It does not clarify the semantics of 'enabled' or whether omitted IDs cause issues.

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 pair ('enables or disables a command or an event listener') and covers both target types. It is distinguishable from siblings like create_command, delete_command, and get_command, though it does not explicitly name them.

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

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

The constraint 'Pass one of command_id or event_listener_id' gives a concrete invocation rule, which is useful since the schema doesn't encode the mutual exclusivity. However, there is no guidance on when to toggle vs. delete or recreate, and no prerequisites (permissions, app scope) are mentioned.

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 destructiveHint=true, and the description earns its keep by explaining the mechanism of destruction: data is a full replacement, and dropping the flow_source_id of existing buttons or select menus deletes their flows. That is exactly the kind of consequence an annotation cannot convey. It does not discuss permissions, reversibility, or recovery after a bad write.

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 dense sentences, front-loaded with the operation, followed by the replacement warning and the concrete pitfall. No restated name/title, no filler.

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

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

For a 6-parameter mutation tool with a nested free-form object, no output schema, and intermediate schema coverage, the description supplies the prerequisite read step and the highest-risk side effect. Minor gaps: whether omitted fields are left unchanged versus cleared, and what a version conflict returns (the latter is partly handled by the version parameter's schema text).

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%, and the description compensates by mapping 'name, description or content' to the name/description/data parameters and by adding a nested-object constraint on data ('keep the flow_source_id of existing buttons and select menus') that the schema leaves completely open. message_id and the partial-update semantics of optional fields remain unaddressed.

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 concrete verb and resource ('Changes the name, description or content of a message template') and enumerates the mutable fields, so the agent knows exactly what is modified. It is clearly distinct from create_message/get_message by implication, though it never names a sibling 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?

Provides explicit workflow guidance: 'data replaces the whole message, so start from get_message.' That is a real when-to-use rule that routes the agent to a prerequisite tool. It lacks an explicit when-not-to-use clause (e.g. prefer create_message / edit_flow), so it stops 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?

Beyond the destructiveHint annotation, the description explains exactly what is replaced and when user edits are lost, plus an explicit 'ask first' safety instruction. It also describes a preview path via get_template, adding valuable behavioral context for a destructive update.

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

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

The description is compact and front-loaded: the core update behavior comes first, followed by replacement semantics and the safety warning. Every sentence contributes useful information with no filler.

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

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

For a destructive mutation with no output schema, the description covers the core behavior, destructive overwrite risk, required caution, and a preview alternative. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents app_id, template_id, overwrite, and parameters. The description reinforces the meaning and risk of overwrite but does not add syntax or semantics for the parameters object or other fields beyond the schema.

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

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

The description states a specific verb and resource: updating an app's installed template to the template's newest version. It distinguishes this from merely installing a template by describing the existing app/template relationship and replacement behavior.

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

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

It gives clear usage context by advising the agent to ask first before using overwrite because user changes are lost. It also points to get_template with app_id as a preview step, though it does not explicitly compare with the sibling install_template tool.

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