aidelly

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

Annotations already indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the specific actions but does not disclose side effects like notifications, irreversibility, or state changes. Given the tool's complexity (9 parameters, no output schema), more behavioral context would be helpful.

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

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

The description is a single sentence that front-loads the HTTP method and path, immediately conveying the tool's purpose. It is concise with no wasted words.

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

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

Given the high parameter count (9) and lack of output schema, the description is minimal. It does not explain the response format, error conditions, or what happens after an action. The sibling list is large, but the description provides enough to differentiate usage.

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 67%, and the description does not elaborate on any parameters. While many parameters are self-explanatory in the schema, the description adds no additional meaning. For parameters like 'body' and 'query' described as overrides, the description could clarify usage but doesn't.

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

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

The description clearly states the verb (approve, reject, return_to_draft, comment) and resource (pending posts), and specifies scope (one or many). It also mentions authorization (Owner/admin only) and API status (Public API preview), distinguishing it from sibling tools like aidelly_list_pending_approvals or aidelly_get_approvals.

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

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

The description provides authorization context ('Owner/admin only') and enumerates allowed actions, making it clear when to use this tool. However, it does not explicitly state when not to use it or suggest alternatives, though the sibling list offers tools for listing or viewing approvals separately.

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

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

Annotations already indicate a write operation (readOnlyHint: false) and non-destructive behavior. The description adds the constraint 'root domain' but doesn't disclose other behavioral traits like duplicate handling or reversibility. It meets a baseline but adds limited context beyond the annotations.

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

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

The description is a single sentence, concise and front-loaded. It avoids fluff but could benefit from slightly more detail without becoming verbose. It earns a 4 for efficient communication.

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

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

Given the tool's 7 parameters, nested objects, required idempotency_key, and lack of output schema, the description is insufficient. It does not explain the response format, idempotency behavior, or how parameters like body and query override work. The tool's complexity demands a richer description.

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

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

With only 43% schema description coverage, the description adds little to parameter understanding. It mentions 'domain' but does not explain idempotency_key, display_name, brand_id, or the optional body/query overrides. The schema itself lacks descriptions for most parameters, and the description does not compensate.

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

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

The description clearly states the tool's action: 'Register a competitor root domain to track in the workspace.' It uses a specific verb (register) and resource (competitor root domain), and distinguishes itself from sibling tools like aidelly_list_competitors.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites (like needing workspace context), and no mention of when not to use it. It lacks explicit usage context.

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

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

The description adds no behavioral context beyond what the annotations already provide. Annotations indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description does not mention idempotency, error handling, or what happens on duplicate handles.

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

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

The description is a single sentence, which is concise but sacrifices necessary detail. While front-loaded with the action, it does not earn its place by providing comprehensive information. It could be expanded without becoming overly long.

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

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

Given the tool's complexity (8 parameters including optional ones, no output schema, and basic annotations), the description is insufficient. It lacks details on parameter usage, return values, error conditions, and idempotency. The tool's context is not fully captured.

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 38%. The description does not explain any parameters beyond the overall action. For example, 'handle' and 'platform' are not described, and 'idempotency_key' and 'brand_id' lack context. The description fails to add meaning to the 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 clearly states the action 'register' and the resource 'creator handle on a specific platform'. It effectively communicates the tool's purpose. However, it does not explicitly distinguish from the sibling tool 'aidelly_add_competitor', which could be similar in nature.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of when not to use it. Given the lengthy sibling list, the lack of usage context is a significant gap.

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

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

Annotations already indicate mutation (readOnlyHint=false) and openness to unknown fields (openWorldHint=true). The description adds context about appending to the tail and distribution timing, but does not explicitly disclose idempotency behavior (though idempotency_key is in schema) or error conditions. With annotations providing baseline, description contributes moderate value.

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?

Single sentence that is front-loaded with the core purpose (add items to queue tail). No wasted words, structure is optimal for quick comprehension.

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

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

Given the complexity (7 params, nested objects, idempotency key, no output schema), the description is too brief. It does not explain prerequisites, error handling, return format, or consequences of repeated calls. The agent would lack sufficient context to use the tool reliably.

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 has 7 parameters with 43% description coverage (some fields lack descriptions like brand_id and idempotency_key). The tool description adds no parameter-level information beyond what's in the schema. It does not explain how to obtain the queue ID, the role of idempotency_key, or the meaning of brand_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?

The description clearly states the tool adds content items to a queue tail for distribution at next available slots, using the HTTP method and path. It distinguishes from siblings like create_queue (creates queues) and list_queues (lists queues).

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 specify when to use this tool versus alternatives, nor does it mention prerequisites (e.g., queue must exist) or conditions for idempotency. Some implicit context is provided by the action verb, but no explicit guidance.

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

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

Beyond the annotations (readOnlyHint=false), the description details HTTP 201/207 partial-failure semantics, per-item results with index/status/error, acceptance-vs-delivery polling, and pre-write rejection when exceeding daily limits. This significantly adds context without contradicting any annotation.

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 information-dense, front-loads the main purpose, and every sentence adds behavior or usage value. It remains readable despite covering status codes, polling, rate limits, and quota rejection.

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

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

Given no output schema, the description thoroughly explains return formats (201/207), per-item result structure, and follow-up behavior. Combined with schema coverage 67%, the description covers the essential invocation and post-call 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?

The schema covers 67% of parameters with descriptions, and the tool description points to 'the same shape as aidelly_create_post' as a reference for item fields. It does not add new meaning to idempotency_key or workspace_id, but the pointer to the sibling is helpful.

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

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

The description opens with 'Create up to 50 scheduled posts in one call,' which names the specific action, resource, and scale. This clearly distinguishes it from single-post siblings like aidelly_create_post and aidelly_create_scheduled_post.

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 explains the batch context, notes the rate limit is charged per post ('saves round trips, not quota'), and directs follow-up polling for each created id. It does not explicitly state when to choose bulk over looping single-post calls, but the trade-off is clear.

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

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

The annotations already indicate destructiveHint=true and readOnlyHint=false, signaling a write/delete operation. The description adds the context that the resource is a 'scheduled post', but does not elaborate on whether cancellation deletes or merely unschedules the post, nor does it mention authorization requirements or side effects.

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

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

The description is a single sentence, which is concise but insufficient. With six parameters, nested objects, and no output schema, one sentence cannot adequately inform the agent. The structure is front-loaded but lacks necessary 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?

Given the tool complexity (6 parameters, 2 required, nested objects, no output schema) and the presence of a confusingly similar sibling, the description is severely incomplete. It does not explain the workflow, return values, or how the idempotency key should be used, leaving the agent underinformed.

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 mention any parameter. It fails to clarify the purpose of key parameters like 'id' (the post UUID) and 'idempotency_key', nor does it explain the meaning of nested objects 'body' and 'query'. The description should compensate for the sparse schema but does not.

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 the verb 'Cancel' and resource 'scheduled post', clearly indicating the tool's function. However, there is a sibling tool named 'aidelly_cancel_scheduled_post' which performs a very similar action, and the description does not differentiate between them, causing potential confusion.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as the overlapping sibling 'aidelly_cancel_scheduled_post' or other post-related tools. No context about prerequisites or post-cancellation effects 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 indicate destructive and idempotent behavior. Description adds that pending recycles are also cancelled, which is a useful behavioral detail beyond annotations.

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

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

Single sentence, front-loaded with purpose. Could omit 'DELETE /scheduled-posts/{id}' as it does not add significant value beyond the tool name.

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

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

For a destructive action with 5 parameters, the description lacks details about response, effects beyond cancellation, or prerequisites (e.g., permissions). No integration of schema hints like workspace_id guidance.

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 40% (only workspace_id and query have descriptions). The tool description adds no parameter information, failing to compensate for the low schema coverage.

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

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

Description clearly states 'cancel a scheduled post (and its pending recycles)' with HTTP method and resource path. It distinguishes from siblings like 'aidelly_cancel_post' by specifying 'scheduled', but does not explicitly contrast with similar sibling 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?

No guidance on when to use this tool versus alternatives (e.g., 'aidelly_cancel_post'). No mention of prerequisites, context, or when not to use it.

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

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

Annotations already indicate `readOnlyHint=false` and `destructiveHint=false`. The description adds behavior: 'Verifies credentials then kicks off initial sync.' This provides some context but does not disclose potential side effects, reversal options, or error states. With annotations present, description adds moderate value.

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 that are front-loaded with the endpoint and action. Every word is necessary. No fluff or redundancy. Highly concise and structured for quick scanning.

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

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

With 8 parameters (4 required), nested objects, no output schema, and low schema coverage, the description is insufficient. It omits return value details, prerequisites like needing a workspace ID, and steps after connecting. The 'Public API preview' note hints at instability but lacks completeness for an agent to use the tool autonomously.

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 low (38%), and the description adds no parameter explanations. Key parameters like `idempotency_key`, `brand_id`, `workspace_id`, and complex `credentials` structure are not explained in the description. The schema itself has some descriptions, but the tool's description should compensate for low coverage, which it fails to do.

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

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

The description clearly states the HTTP method and resource ('POST /ecommerce/stores'), the action ('connect a new store'), specifies the supported providers (Shopify, WooCommerce, Etsy, Wix), and mentions the process (verifies credentials, kicks off sync). This distinguishes it from siblings like `aidelly_disconnect_ecommerce_store` and `aidelly_sync_ecommerce_store`.

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 lacks guidance on when to use this tool. It does not mention prerequisites (e.g., workspace), who should use it, or scenarios where alternative tools might be better. Only a vague 'Public API preview' hint is given, providing no useful usage context.

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

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

The description adds no behavioral information beyond what annotations already indicate (readOnlyHint=false, destructiveHint=false). It does not disclose side effects, idempotency behavior, or the asynchronous nature of creating a job. Since it adds zero context, the score is low.

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 line is extremely short, but the brevity is under-specification rather than conciseness. The description fails to include any explanatory content and would be better replaced with a minimal sentence describing the tool's function.

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 complex tool with nested posts array, required idempotency_key, and no output schema. The description is entirely inadequate, providing no context about the request body, side effects, or result handling. It is almost as minimal as a single-word description.

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 50%, and the description provides no additional explanation for parameters. The body/posts structure and the relationship between brand_id, workspace_id, and idempotency_key are left unexplained, so the description does not compensate for the schema's gaps.

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 is only 'POST /calendar/bulk-fill', which gives the HTTP method and path but does not explain what a 'bulk-fill' job does. It does not distinguish this from siblings like aidelly_bulk_create_posts or aidelly_create_scheduled_post. The verb+resource is present but the actual action is unclear.

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 is provided on when to use this tool versus alternatives. The description lacks any context about use cases, prerequisites, or exclusions, leaving the agent without direction for appropriate selection.

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 indicate mutability (readOnlyHint=false) but the description adds critical information: the raw token is returned exactly once and must be stored securely. This goes beyond the structured fields.

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

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

The description is extremely concise—two sentences that cover the action, HTTP method, and a key behavioral note. No wasted words.

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

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

The tool has 8 parameters and no output schema, yet the description only mentions the returned token. It omits details about the response structure, required workspace context, or potential error states, leaving gaps for an agent.

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 75%, so the schema already documents most parameters. The description does not elaborate on parameter meanings or usage beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool creates a 'magic-link review portal' via POST, and the sibling tools include list and revoke variants, making the purpose distinct and unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives like aidelly_list_client_review_links or aidelly_revoke_client_review_link. A brief mention of use cases or exclusions would improve this.

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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds no behavioral context beyond these, such as side effects, authentication needs, or link properties. With openWorldHint=true, more detail would be beneficial.

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

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

The description is a single concise sentence with no unnecessary words. It efficiently conveys the core action, though it could benefit from slightly more detail without losing conciseness.

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

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

Given 7 parameters, no output schema, and a non-trivial action, the description is too sparse. It omits return value hints, prerequisites (e.g., workspace existence), and side effects. The annotations partially compensate, but the description alone is insufficient for an agent to fully understand the tool's context.

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

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

Schema coverage is 57%, meaning some parameters lack descriptions (e.g., brand_id, idempotency_key). The description does not explain any parameter's role or constraints, failing to compensate for the missing schema details. Parameters like 'body' and 'query' remain ambiguous despite generic schema descriptions.

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

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

The description clearly states the verb 'Create' and the specific resource 'OAuth connect link', which distinguishes it from sibling tools like 'aidelly_create_short_link' or 'aidelly_create_client_review_link'. The purpose 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?

The description provides no guidance on when to use this tool versus alternatives such as 'aidelly_list_connect_links' or 'aidelly_revoke_connect_link'. There is no mention of prerequisites or context for selection.

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

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

Annotations already indicate mutability (readOnlyHint=false). The description adds context like 'multi-channel fan-out' and 'per-platform transformations', but does not explain important behavioral traits such as the idempotency_key requirement or that workspace_id is required for creation. Since annotations are present, the bar is lower, but gaps remain.

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

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

The description is a single sentence of 14 words, front-loaded with the HTTP method and core purpose. No extraneous words.

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

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

Despite good annotations and schema, the description lacks context about the return value (no output schema), the requirement for workspace_id during creation, and when this tool is appropriate relative to similar tools. This is insufficient for a tool with nested parameters and no output schema.

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

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

Schema description coverage is 75%, and the schema already includes clear descriptions for most parameters. The tool description adds no additional meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the tool creates a 'multi-channel fan-out preset with per-platform transformations', specifying the verb (create) and resource (destination preset). It distinguishes from siblings like list and preview.

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 implies usage for creating presets but provides no explicit guidance on when to use this tool vs alternatives (e.g., preview_destination_preset). No prerequisites or when-not-to-use 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?

The description adds significant behavioral context beyond the annotations: drafts are saved but never publish, draft_planned_for is a planning date only (not a scheduler), and API keys require explicit drafts:write scope with no implicit grant. These details are not present in the annotations and help the agent understand side effects and prerequisites.

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

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

The description is three sentences, each adding distinct value: the core purpose, a field clarification, and authorization/input requirements. It is front-loaded with the primary purpose and contains no redundant or filler 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?

For a create tool with 12 parameters and no output schema, the description covers essential behavior (never publishes), clarifies a potentially confusing field (draft_planned_for), and highlights the critical auth scope requirement. It does not mention workspace_id requirements, but that is documented in the schema. The lack of return-value description is acceptable given the absence of an output schema, but the description is not exhaustive.

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

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

Schema description coverage is 83%, and the schema already documents the key parameters (platform, platforms, draft_planned_for, workspace_id, etc.). The description only restates constraints already in the schema, such as the platform/platforms requirement and the non-scheduling nature of draft_planned_for, without adding new parameter-level semantics.

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

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

The description clearly states the verb ('Create') and resource ('draft'), and the phrase 'never publishes' strongly distinguishes it from sibling tools like create_post and create_scheduled_post. This makes the tool's purpose unambiguous.

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

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

The description provides useful usage context: drafts are work-in-progress and never publish, so this tool is appropriate for non-publishing content. It also specifies critical prerequisites (platform/platforms requirement, drafts:write scope). However, it does not explicitly name alternative tools for publishing scenarios, though the 'never publishes' phrase implies the exclusion.

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

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

Annotations already indicate it's a write (readOnlyHint false) and non-destructive. The description adds context about workspace board and optional seeding, but does not disclose idempotency behavior, side effects, or exact return value. Neither contradicts 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?

Single sentence, 16 words, efficient and immediately clear. No unnecessary information.

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

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

Given 10 parameters (including required idempotency_key) and no output schema, the description lacks essential context: what is returned, how the idea board works, or next steps. It fails to compensate for missing information beyond 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?

With 70% schema coverage, the description adds little beyond the schema. It mentions 'initial body or topic', which are already described in the schema. Does not clarify complex parameters like body, query, or idempotency_key usage.

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

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

The description clearly states the verb 'Create' and the resource 'new idea on the workspace's idea board', with optional seeding. It distinguishes from sibling tools like aidelly_create_post or aidelly_create_task by specifying the idea board context.

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 tool versus alternatives like aidelly_list_ideas or other create tools. No mention of prerequisites (e.g., workspace_id required for creation) or scenarios where this tool is appropriate.

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

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

Annotations indicate write operation (readOnlyHint=false) and non-destructive. The description adds key behavioral context: requires PUT to Supabase URL, client must be shell-capable, sandbox restrictions. No contradictions.

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

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

Three sentences, front-loaded with core action, no redundant phrasing. Every sentence adds value: function, usage constraint, alternative referral.

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?

Describes core function and client constraints, but lacks details on return value structure, parameter meanings, and possible side effects. With no output schema, more explanation of what is returned would improve completeness.

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

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

Schema coverage is low (33%) and description does not compensate. It does not explain any parameters beyond the overall action. Parameters like idempotency_key, file_size limits, or folder are left undocumented.

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

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

The description clearly states it creates a signed upload URL and media record for shell-capable clients, and explicitly distinguishes from aidelly_upload_media for browser-sandboxed clients. The verb 'Create' with specific resource and client type 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?

The description provides explicit guidance: use for shell-capable clients, do NOT use for browser-sandboxed chat clients, and directs to aidelly_upload_media as alternative. This is exemplary 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 convey that the tool is not read-only, not destructive, and open-world. The description adds limited behavioral context, such as the platform constraint and that photos are separate from posts. It does not elaborate on idempotency (despite the idempotency_key parameter) or other behavioral traits beyond what annotations provide.

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

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

The description is extremely concise: two sentences that immediately convey the tool's purpose and key constraint. No wasted words, front-loaded with essential information.

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

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

Given the tool's complexity (11 parameters, no output schema), the description is minimal. It covers the core purpose and limitation but does not explain return values, error conditions, or success behavior. The schema's detailed parameter descriptions compensate somewhat, but the tool lacks completeness for an agent to fully understand its effects without additional context.

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

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

Schema description coverage is 73%, so the schema already provides meaning for most parameters. The description adds no additional parameter-level details, relying on the schema's descriptions. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states the tool's purpose: uploading a photo to a connected platform's media gallery, distinct from posts. It specifies the current limitation to 'google_business' only, which differentiates it from sibling tools like 'aidelly_create_post' and 'aidelly_upload_media'.

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 indicates when to use the tool (uploading photos to a media gallery) and the platform limitation. However, it does not explicitly mention when not to use it or provide alternative tool names for other media operations, though the context implies such distinctions.

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

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

Annotations already indicate the tool is read-only (false) and not idempotent. The description adds that a 201 response means 'accepted, not delivered', which clarifies the asynchronous behavior. It does not elaborate on side effects, permissions, or error conditions beyond the annotations.

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

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

The description is three sentences long, each earning its place: purpose, async behavior with polling, and a key prerequisite. It is front-loaded and avoids redundancy.

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

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

Given the tool's complexity (12 parameters, nested objects, no output schema), the description covers the essential behavioral context: async acceptance, polling requirement, and a platform-specific prerequisite. It omits error handling and retry logic but is sufficient for correct usage.

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 around 50%, with many parameters already well-documented in the schema. The description adds specific advice for the `platform_specific.board_id` parameter (use `aidelly_list_pinterest_boards`), which improves clarity. However, it does not significantly enrich understanding of other 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 clearly states the tool accepts a post for immediate asynchronous publishing or future scheduling. It distinguishes from siblings like `aidelly_bulk_create_posts` and `aidelly_create_scheduled_post` by covering both immediate and scheduled creation and emphasizing the async nature with polling guidance.

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

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

The description provides explicit when-to-use and post-usage steps: polling `aidelly_get_post` for immediate posts and using `aidelly_list_pinterest_boards` before Pinterest posts. It does not mention when not to use the tool or alternatives like `aidelly_create_scheduled_post`, but the context is clear enough.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds useful behavioral context: @mention parsing is automatic, and replies must reference the root comment. These details go beyond the annotation flags, giving the agent a better mental model of tool behavior.

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

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

Two sentences, front-loaded with the primary purpose and zero filler. Every clause adds value: required body, automatic @mention parsing, and reply semantics. High signal-to-noise ratio.

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 an 8-parameter mutation tool with no output schema, the description covers the core behavior but omits critical context such as the meaning of `id` (presumably the post ID) and the role of `idempotency_key`. The schema's workspace description covers the workspace requirement, but overall the agent would need to make assumptions about several parameters.

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 about 63% (5 of 8 parameters have descriptions). The description reinforces that `text` is required and @mentions are automatic, but that is already in the schema. It adds a meaningful constraint for `parent_comment_id` (must point to the root comment). However, required fields like `idempotency_key` and `id` remain unexplained in both schema and description, leaving a gap.

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 begins with a specific verb+resource: 'Create a comment on a post.' This clearly distinguishes it from sibling tools like create_post (creates a post itself) and update_post_comment (modifies an existing comment). The additional details about @mentions and replies further clarify the scope.

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

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

The description provides clear context: text body is required and replies need parent_comment_id pointing to the root comment. This offers practical usage guidance for the main scenarios. However, it does not explicitly mention alternative tools for editing or deleting comments, so it falls short of a perfect score.

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

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

Annotations indicate a write operation (readOnlyHint false) with potential side effects (openWorldHint true) and no idempotency. However, the description fails to disclose behavior like duplicate handling, required workspace_id (described as optional but required for creation), or error conditions. No mention of rate limits or auth.

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

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

The description is a single, front-loaded sentence with the HTTP method, resource, and key feature. No wasted words.

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

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

With 9 parameters, nested objects, and no output schema, the description is too brief. It omits details on how workspace_id is required for creation, idempotency semantics, and return values. The tool's place in the queue lifecycle (create then add items) is not mentioned.

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 78%, so baseline is 3. The description adds minimal value beyond schema descriptions (e.g., 'recurring weekly time slots' for slots). Parameters like idempotency_key and brand_id lack explanation in either the description or schema.

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

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

The description clearly states the verb ('create') and resource ('content distribution queue') with a specific feature ('recurring weekly time slots'). It distinguishes from siblings like aidelly_add_queue_items and aidelly_list_queues by focusing on queue creation.

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 implies the tool is for creating queues but does not provide explicit guidance on when to use it versus alternatives (e.g., aidelly_add_queue_items for adding content). No prerequisites, when-not-to-use, or context about the queue lifecycle 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?

The description adds context about synchronous execution and building from connected accounts. However, it contradicts the annotation 'idempotentHint: false' by stating the tool requires an Idempotency-Key header, implying idempotency. This inconsistency reduces transparency. No mention of failure modes or permissions beyond the header requirement.

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

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

The description is concise with two sentences. The first sentence effectively conveys the main purpose and behavior. The second adds a key requirement. No unnecessary content, though it could be slightly more structured to separate purpose from requirements.

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 12 parameters, no output schema, and low schema description coverage, the description is insufficient. It fails to explain return value, error handling, or how to construct the request beyond the header. The contradiction with annotations further undermines completeness.

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

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

Schema description coverage is only 25%, with most parameters (e.g., brand_id, sections, commentary, templateId, includeComparison) lacking descriptions. The description mentions date range but does not explicitly correlate to 'dateRangeStart' and 'dateRangeEnd' parameters. The IDempotency-Key header is mentioned but not reflected in the schema. The description does not compensate for the low coverage.

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

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

The description clearly states that the tool creates a report for a date range and synchronously builds an analytics snapshot from connected workspace accounts. It distinguishes from sibling tools like 'aidelly_create_report_schedule' or 'aidelly_list_reports'.

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 mentions the requirement of an Idempotency-Key header, which is a usage guideline. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., creating a scheduled report or viewing existing reports). The usage context is implied but not fully articulated.

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

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

Annotations already cover read-only, destructive, idempotent hints. Description adds the snapshot/live cadence distinction, but does not disclose permissions, rate limits, or side effects beyond annotation hints.

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?

Single sentence with no waste, front-loads the purpose and mode variations.

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 and 11 parameters; description does not explain return value, post-creation steps, or how to handle the open-world hint (additional fields).

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 82% (high), so description's lack of parameter-specific detail is acceptable; baseline 3 is appropriate.

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

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

The description clearly states the action (create), resource (shareable report link), and variations (snapshot or live with cadence). It distinguishes from siblings like create_report_schedule by specifying 'shareable report link'.

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 tool vs alternatives, no prerequisites, and no mention of required conditions like workspace_id being required for creation.

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 provide mutation context. Description adds soft cap and duplicate name error behavior. However, it does not disclose authorization requirements, side effects, or rate limits, which are valuable for a mutation tool.

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 are efficient and front-loaded. Could be improved by explicitly listing key behavioral notes (e.g., idempotency key usage) but currently no waste.

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?

Tool has 10 parameters (4 required) and no output schema. Description lacks explanation of return values, error handling beyond name conflict, or how to use required fields like idempotency_key. Incomplete for the complexity.

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

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

Schema description coverage is 50% (5/10 params documented). The description adds no parameter-level meaning beyond the schema, leaving half of parameters unexplained. The soft cap is a global constraint, not parameter-specific.

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

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

The description clearly states the action ('Create a new report schedule') and adds a distinguishing constraint ('Soft-capped at 10 active schedules per workspace'). It differentiates from sibling tools like 'create_report' and 'update_report_schedule'.

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 explicit guidance on when to use this tool vs alternatives (e.g., 'create_report' for reports, 'update_report_schedule' for modifications). The schema includes a usage hint for workspace_id but no when-to-use context.

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

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

Annotations provide basic traits (not read-only, not idempotent, not destructive), but the description adds little beyond stating 'synchronous'. It does not disclose that the operation requires an idempotency key for deduplication, nor does it mention side effects like resource creation or potential errors. There is no contradiction with annotations.

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

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

The description is a single sentence that efficiently conveys the core action and target. It uses active voice and is front-loaded with the key verb 'run'. No redundant or vague phrases.

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

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

Given the absence of an output schema, the description should explain what the tool returns, but it does not. It also omits mention of prerequisites (e.g., workspace_id requirement for creating content) and potential errors. However, it adequately describes the main workflow for a moderate-complexity 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?

With schema description coverage at 55%, the description adds no additional meaning to any parameter. It does not explain the purpose of idempotency_key, workspace_id, or sourceRef beyond what the schema already provides. The schema's shape enum list is detailed, but the description fails to compensate for the lower coverage.

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

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

The description clearly states the tool's purpose: running a synchronous repurpose job that extracts, distills, and generates output for one (medium, shape) target. It specifies the action, resource, and scope, distinguishing it from sibling tools like get_repurpose_job and list_repurpose_jobs.

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 implies the tool is for creating a single repurpose job, but it does not explicitly state when to use it versus alternatives, such as when to retrieve results or list jobs. There is no guidance on prerequisites like required workspace permissions.

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

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

The description adds behavioral context beyond the annotations: auto-recycle limits (up to 3 reposts + 3 reshares), pending state under Team Approvals, and 'Public API preview' indicating instability. It does not contradict annotations and provides useful side-effect information.

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

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

The description is concise and front-loaded, starting with the HTTP method and endpoint, then the action, followed by the most important options. Every sentence adds value 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?

This is a complex creation tool with 12 parameters, nested objects, and no output schema. The description omits response format, error conditions, and details about required parameters. The team approvals note is helpful but insufficient for an agent to confidently invoke the 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?

With only 42% schema description coverage, the description was expected to compensate for undocumented parameters. It only explains the recycle array, but leaves required fields like idempotency_key, platform, scheduled_at, and payload largely unexplained. The schema covers some parameters, but key semantics remain missing.

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

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

The description clearly states the action ('schedule a post') and the resource ('/scheduled-posts'), and distinguishes it from siblings by mentioning optional auto-recycle entries. It also adds a specific behavioral context about Team Approvals pending state.

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

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

The description provides clear context for when to use this tool: scheduling posts with optional recycle entries. It mentions a conditional behavior (Team Approvals pending) but does not explicitly contrast with alternatives like aidelly_create_post or aidelly_create_draft. No exclusions are given, so it earns a 4 rather than 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?

The description only says 'create', giving no details about side effects or behavior. The openWorldHint annotation hints at side effects, but the description does not elaborate.

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?

Extremely short, but it is underspecified rather than concise. The single sentence omits critical context for a tool with 7 parameters.

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

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

The tool has no output schema, and the description fails to explain what a short link is, how it behaves, or what the response looks like. Incomplete given the complexity.

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

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

The description adds no meaning beyond the input schema. For the 3 parameters without schema descriptions (brand_id, idempotency_key, target_url), the description offers no clarification.

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

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

The description clearly states it creates a manual short link on the workspace, but it does not differentiate from sibling tools like aidelly_create_client_review_link or aidelly_create_connect_link.

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 tool versus alternatives, or any prerequisites like requiring a workspace context.

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

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

Annotations indicate a mutable operation (readOnlyHint=false), but the description does not elaborate on behavioral traits such as idempotency, conflict handling, required permissions, or side effects. The description adds no value beyond the annotations.

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

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

The description is a single sentence, which is concise but overly minimal. It could include more useful information (e.g., about idempotency or required workspace_id) without becoming verbose.

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

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

Given the tool's complexity (13 parameters, no output schema), the description is incomplete. It lacks details on return value, idempotency key purpose, and the need for workspace_id. This may hinder correct invocation by an AI agent.

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 high (85%), so the parameters are well-documented in the schema. However, the description does not add any additional meaning or usage context for parameters. Baseline 3 is appropriate.

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

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

The description 'Create a new task in the workspace.' uses a specific verb and resource, clearly distinguishing it from sibling tools like aidelly_update_task, aidelly_delete_task, and aidelly_create_idea.

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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. While the schema includes a note on workspace_id, the description itself offers no 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 indicate non-readOnly and non-destructive behavior. The description adds no further behavioral context (e.g., idempotency issues, required permissions, side effects). It does not leverage the openWorldHint or mention that creating a webhook may have costs or rate 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?

The description is very short (7 words), which is concise but lacks necessary depth. It is a single sentence with no structure or additional detail. While not verbose, it is under-specified.

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 9 parameters, no output schema, and a complex domain (webhooks), the description is incomplete. It does not describe the return value, usage patterns, or tie into the sibling tool ecosystem (e.g., how to manage created webhooks).

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 33%. The description does not explain any parameters beyond hinting at 'events' via 'post lifecycle events'. It adds minimal value to the schema, leaving the agent to infer parameter meanings from names alone.

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

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

The description clearly states the action ('Create a webhook subscription') and the resource ('post lifecycle events'). This distinguishes it from sibling tools like aidelly_delete_webhook, aidelly_list_webhooks, etc.

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 tool vs alternatives, no prerequisites or exclusions mentioned. The description does not help the agent decide between create_webhook and other webhook-related tools.

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

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

The description adds minimal behavioral context beyond the annotations. It does not address the idempotency_key parameter's role despite the annotation idempotentHint: false, which contradicts the schema's inclusion of that parameter. No mention of response behavior, side effects, or rate 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?

The description is very concise (one short sentence), but this comes at the expense of completeness. It lacks structure and does not differentiate itself from other create tools. It could be improved by front-loading key parameters.

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

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

Given the complexity (7 parameters, no output schema) and the presence of many sibling tools, the description is insufficient. It does not explain what a workspace is, what the required parameters do, or what the response looks like, which is necessary for an agent to correctly invoke the 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?

With only 43% schema description coverage, the description does not list or explain any parameters. It fails to clarify the required 'name' and 'idempotency_key' or the optional 'workspace_type' and 'brand_id', leaving the agent to infer from schema alone.

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

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

The description clearly states the verb 'create' and the resource 'workspace', and distinguishes it from siblings like update_workspace or delete_workspace by specifying 'new workspace'. However, it does not elaborate on the scope ('for the API key owner') which is 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?

The description provides no guidance on when to use this tool vs alternatives such as aidelly_list_workspaces (to avoid duplicates) or aidelly_update_workspace. There is no mention of prerequisites or context.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. The description adds no further behavioral context, but since annotations cover the safety profile, a neutral score 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?

The description is extremely short but lacks essential content. It is under-specified rather than concise, providing no useful information beyond the endpoint path.

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

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

No output schema exists, yet the description does not explain what the tool returns (e.g., success status, error handling). The tool's complexity is moderate, but the description is incomplete for effective use.

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

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

Schema description coverage is only 40%, and the required parameters 'id' and 'idempotency_key' lack descriptions. The description provides no additional meaning beyond the schema, failing to compensate for the low coverage.

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

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

The description 'DELETE /calendar/events/{id}' is barely more than a tautology; it repeats the HTTP method and path without explaining that this tool deletes a calendar event. While the HTTP verb implies deletion, the purpose is not explicitly stated.

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 is provided on when to use this tool versus alternatives like patching or getting events. Missing prerequisites or context for deletion, such as requiring the event ID or idempotency key.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context (e.g., permanence of deletion, side effects). It does not contradict annotations.

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

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

The description is extremely short (one phrase) but under-specified. It lacks essential information, making it insufficient rather than appropriately concise.

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

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

The tool is destructive with 5 parameters and no output schema. The description fails to explain what happens after deletion, error cases, or the resource it operates on. Incomplete for understanding tool behavior.

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

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

With only 40% schema description coverage, the description should compensate by explaining parameter meanings, especially for required fields like 'id' and 'idempotency_key'. It does not mention any parameter.

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

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

The description 'DELETE /content-automations/{id}' clearly indicates an HTTP DELETE operation on a content automation resource, but it does not explicitly state that the tool deletes the automation. It is not a tautology but lacks a specific verb+resource statement.

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 is provided on when to use this tool versus alternatives like GET or PUT for the same resource. There is no mention of prerequisites, context, or when not to use.

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

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

The description discloses a critical behavioral trait beyond the annotations: existing API keys need the `drafts:write` scope and no implicit grant occurs. This adds meaningful context about auth requirements, which is not present in the annotations. It also clarifies the nature of drafts, adding value beyond the destructiveHint.

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 highly concise, with three sentences that each add value: clear purpose, draft context, and auth warning. No redundant or filler content exists, and the most critical information is front-loaded.

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

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

While the description covers purpose, draft nature, and access scope, it leaves gaps for a deletion tool with 5 parameters and no output schema. It does not clarify whether workspace_id is required for delete operations, nor does it explain the role of the required idempotency_key. The query parameter semantics are also vague, making the tool less than fully transparent.

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

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

With schema description coverage at only 40%, the description should compensate for undocumented parameters. It only mentions 'by ID' and does not explain idempotency_key, brand_id, or the workspace_id requirements. The schema itself lacks descriptions for these required/optional fields, so the agent receives insufficient 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 starts with 'Delete a draft by ID,' which is a specific verb+resource statement that clearly distinguishes this tool from sibling draft operations like create, get, update, and list. It also clarifies the nature of drafts, reinforcing the purpose.

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

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

The description provides clear context that drafts are work-in-progress content that never publish, implying this tool is for deleting unpublished drafts rather than published content. However, it does not explicitly name alternative tools or exclusions, so it falls short of full 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?

The description does not disclose any behavioral traits beyond what annotations already indicate (destructiveHint, idempotentHint). For a destructive operation, it lacks context about irreversible effects, required permissions, or cascading deletions.

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 extremely short but fails to convey essential information. It is under-specified rather than concise; the single sentence does not earn its place because it provides no more insight than the tool name.

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

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

Given the tool's destructiveness, parameter complexity (5 properties, nested objects), and lack of output schema, the description is severely incomplete. It offers no context on return values, error states, or the operational impact of deletion.

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 description adds no explanatory value for parameters. While the input schema partially documents 'query' and 'workspace_id', the description omits crucial details about 'id' (automation identity) and 'idempotency_key', leaving the agent with incomplete 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 simply repeats the HTTP method and path ('DELETE /inbox/automations/{id}'), which adds no new purpose beyond the tool name. It fails to state what an automation is or what deletion entails, offering only a tautological restatement.

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 usage guidance is provided. There is no mention of when to use this tool vs. other delete operations (e.g., aidelly_delete_calendar_events_id) or any prerequisites like needing to fetch the automation first.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful context by specifying 'soft delete' (implying reversibility or non-permanent removal) and the authorization requirement. This goes beyond what the annotations alone convey.

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

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

The description is a single concise sentence that is front-loaded with the core action and resource. Every word earns its place, and there is no redundant restatement of the tool name.

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

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

Given no output schema and a low parameter description coverage, the description is minimally adequate: it communicates the operation, the soft-delete behavior, and a permission constraint. However, it leaves key required parameters (idempotency_key, commentId vs id) unexplained, so important context 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 only 33%, and the description does not compensate. It does not clarify the distinction between 'id' and 'commentId', explain the required 'idempotency_key', or describe the purpose of 'brand_id' and 'query'. The agent is left guessing about parameter roles.

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

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

The description clearly states the action ('soft delete') and the resource ('a comment'), with a specific verb and object. It distinguishes this tool from sibling delete tools (e.g., delete_draft, delete_task) and from comment management tools like update_post_comment.

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

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

The description gives a clear usage constraint: only the author or workspace owner can delete comments. This tells the agent when the tool can be invoked, though it does not explicitly mention alternatives or when-not-to-use scenarios beyond the permission restriction.

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 value beyond annotations by disclosing soft-delete behavior (sets active=false). However, it does not describe other side effects, authorization needs, or consequences for associated data. Annotations already provide destructive and idempotent hints, partially covering the burden.

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?

Single sentence with no filler. Front-loaded with key information: action, resource, soft-delete, idempotent. Every word adds 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?

No output schema, and description fails to address return values, error conditions, permissions, or the impact on related entities (e.g., reports). For a mutation tool with five parameters, more context is needed.

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 40%, and the description adds no parameter-level details. The word 'idempotent' hints at the idempotency_key parameter but is not explicit. The required 'id' and 'idempotency_key' are not explained. Should compensate for low schema coverage.

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

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

Description clearly states the verb 'delete' and resource 'report schedule', specifies it's a soft-delete (sets active=false), and notes idempotency. This distinguishes it from sibling tools like 'aidelly_update_report_schedule' and 'aidelly_get_report_schedule'.

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 explicit guidance on when to use this tool versus alternatives (e.g., update or get). Lacks context for prerequisites or side effects. The idempotent hint is in annotations but not elaborated.

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

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

The description goes beyond annotations by specifying 'soft-delete' and 'can be restored', which adds important behavioral context not captured by destructiveHint=true or other annotations. It discloses the reversible nature, which is critical for agent understanding.

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

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

The description is a single concise sentence that front-loads the key information. Every word is meaningful, and there is no redundant or extraneous content.

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

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

For a soft-delete tool with no output schema and partial parameter descriptions, the description adequately communicates the core operation. However, it lacks context on restoration mechanisms, side effects, or expected response, which would be helpful for an agent to use the tool effectively.

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 description does not elaborate on any of the 5 parameters. With only 40% schema description coverage, there is a significant gap in explaining the purpose or usage of fields like 'id', 'brand_id', and 'idempotency_key', especially the required idempotency_key. The description fails to compensate for the schema's lack of clarity.

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

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

The description clearly states the tool's action ('soft-delete') and resource ('task'). It distinguishes from a hard delete by noting that the task can be restored, providing precise purpose aligned with the tool name.

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 is provided on when to use this tool versus alternatives like aidelly_delete_calendar_events_id or when not to use it. The description lacks context for decision-making, such as prerequisites or differentiation from other delete tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description reiterates the deletion but does not add behavioral context beyond that, such as authentication requirements or impact on other resources.

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

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

The description is a single sentence, immediately stating the action and target. No wasted words; it is efficiently front-loaded.

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

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

For a deletion tool with 5 parameters and no output schema, the description is minimal. It covers the core action but lacks guidance on parameter usage and does not leverage annotations to explain behavior fully.

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 40%, with several parameters lacking schema descriptions. The tool description adds no meaning beyond 'by ID'; it does not explain idempotency_key, brand_id, workspace_id, or query.

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

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

The description clearly states the verb 'delete', the resource 'webhook subscription', and the method 'by ID'. It is specific and distinguishes this tool from siblings like create_webhook or list_webhooks.

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 is provided on when to use this tool, prerequisites (e.g., need the webhook ID from list_webhooks), or alternatives. The description is purely functional.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds valuable context: 'soft-delete' indicates reversibility, and 'requires confirm_name to match the workspace name' implies a safety check. No contradiction with annotations.

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

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

Two sentences, no redundant words. Front-loaded with HTTP method and core action. Every sentence serves a purpose.

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

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

Despite having 7 parameters and no output schema, the description omits return behavior, deletion effects, and prerequisite steps (e.g., workspace lookup). It relies heavily on schema and annotations, leaving gaps for an agent.

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 low (29%). The description adds meaning only for confirm_name (must match workspace name). Other required parameters like workspaceId and idempotency_key are left unaddressed. Baseline 3 is appropriate as description provides some but insufficient param context.

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 explicitly states 'soft-delete a workspace', combining a specific verb (delete) and resource (workspace). It includes the HTTP method and a key requirement, clearly differentiating from sibling tools like create, update, or list.

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 is provided on when to use this tool versus alternatives (e.g., when to use hard delete or update). The description only mentions a precondition but lacks context about prerequisites like workspace existence or idempotency.

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

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

Description discloses that the credential is revoked and syncs stop, but imported products persist—adds behavioral nuance beyond annotations. Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description clarifies what exactly is destroyed (credential, not products). IdempotentHint=true is not mentioned but implied by the safe-to-retry nature; no contradiction.

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 tight sentence plus a status note. Front-loaded with the core action. Could be more structured (e.g., separate sections), but no fluff.

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

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

Covers main effect and what remains, but lacks output schema (none exists) and does not address idempotency or the role of required parameters. For a destructive operation with 5 params, more detail on usage context and response behavior would improve completeness.

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

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

With 40% schema coverage, the description should compensate but does not describe any parameters. It mentions the store ID in the path, but does not explain required params like idempotency_key or brand_id. The query and workspace_id parameters are left unexplained. Significant gap.

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

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

The description clearly specifies the action: DELETE to revoke credential and stop syncs, with a note that imported products remain. It distinguishes from sibling tools like connect_ecommerce_store and sync_ecommerce_store by naming the specific effect.

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 explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., store must be connected) or contexts where disconnection is appropriate. Sibling tools exist (connect, sync) but no differentiation cues.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds 'Public API preview', indicating instability, and 'Default count 8', which is a behavioral default. No contradiction, but little additional behavioral context beyond annotations.

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

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

The description is very concise with three short segments. It is front-loaded with purpose. However, it could be slightly longer to cover more behavioral context without becoming verbose.

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 7 parameters, 1 required, no output schema, and open-world annotations, the description lacks completeness. It does not explain return values, failure modes, or how parameters interact. 'Brand-aware track' is left undefined.

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 57%, but the description adds no parameter-level information. It merely restates the default count which is already in the schema. For parameters like 'steer', 'brand_id', and 'workspace_id', the description provides no extra meaning.

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

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

The description clearly states the tool generates brand-aware interview questions with a specific verb and resource. It distinguishes itself from sibling CRUD tools by being a generation endpoint. The default count and HTTP method are included.

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 tool versus alternatives. It does not mention any prerequisites, exclusions, or specific contexts beyond the name. The agent must infer usage from the name alone.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds the data content (specific fields returned), which is useful. But beyond annotations, it lacks details on rate limits, pagination, or response behavior.

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

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

Single sentence that packs key information efficiently. Front-loaded with endpoint and purpose. Could be slightly improved by separating details into two sentences, but overall concise.

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?

Lists the main data fields returned (queue, failures, approvals, etc.), which is helpful. However, with no output schema and 4 parameters, it lacks parameter usage guidance and return structure details. Adequate but not complete.

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

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

Schema description coverage is 50%, so some parameters have descriptions. But the description itself provides zero information about parameters (tz, query, brand_id, workspace_id). It does not compensate for the uncovered parameters.

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

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

Description clearly states it's a cross-workspace agency summary with specific data points (queue, failures, approvals, inbox split, credit burn). It distinguishes from per-workspace tools but doesn't explicitly differentiate from other summary tools like get_analytics_summary.

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

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

Mentions required key type ('workspace-unscoped key') which is a usage constraint. However, no guidance on when to use over alternatives, no when-not-to-use scenarios, and no context on prerequisites.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context on the snapshot components but does not disclose additional behavioral traits such as rate limits or authentication requirements. No contradiction exists.

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

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

Single sentence, direct, no redundant wording. Every word contributes to stating the tool's purpose and scope.

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

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

The tool has three parameters and no output schema. The description lists the credit categories returned but omits brand_id semantics and does not clarify the `query` parameter's role. With annotations present, the read-only behavior is transparent, but the lack of output schema means more return detail would improve completeness.

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

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

Schema coverage is 67%, leaving brand_id undocumented. The description does not explain any parameters or compensate for the missing coverage; it only lists credit components, not how they map to 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 the specific verb 'Get' and names the resource 'workspace AI credit balance snapshot' with explicit components (plan credits, trial grants, purchased credits). This clearly states what the tool does and distinguishes it from siblings like get_usage or get_analytics_summary.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention preconditions, exclusions, or related tools. The only usage hint appears in the workspace_id schema description, which is not part of the tool description.

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, idempotentHint, and destructiveHint, so the safety profile is known. However, the description adds no behavioral context such as pagination, authentication needs, rate limits, or return format, providing no value beyond the annotations.

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

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

The description is extremely short but under-specified. It conveys no information beyond the endpoint path, which is not genuine conciseness but a lack of specification. Important behavioral and usage details are absent.

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

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

For a tool with 8 parameters, no output schema, and no parameter explanations, this description is completely inadequate. It fails to explain what the tool returns, how to use it, or how it fits into the broader API. The agent has almost no information to select and invoke it correctly.

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

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

With only 25% schema description coverage, the description was expected to compensate for opaque parameters like type, limit, cursor, brand_id, dismissed, and platforms. It does not mention any parameters, leaving their meaning unexplained. The schema provides only type constraints, not semantic meaning.

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 'GET /analytics/insights' merely restates the HTTP endpoint and resource, which is equivalent to the tool name. It does not explain what kind of analytics insights are returned or how they differ from sibling tools like get_analytics_summary or get_analytics_unified.

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 tool versus alternatives. No context, prerequisites, or exclusions are mentioned. Sibling tools with similar purposes exist, but the description provides no differentiation.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds no behavioral context such as the scope of data covered (e.g., date range, metrics included) or any limitations. It does not contradict annotations.

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

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

The description is extremely short, but this is under-specification, not conciseness. It lacks essential content and is not front-loaded with useful information.

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

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

The tool has 8 parameters, no output schema, and many sibling analytics tools. The description is completely inadequate: it does not explain the return format, what metrics are summarized, or how it differs from other analytics endpoints.

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

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

With only 25% schema description coverage, the description should compensate by explaining key parameters like startDate, endDate, timeframe, or includeActivity. Instead, it provides zero parameter information, leaving the agent to rely solely on the sparse 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 'GET /analytics/summary' is a tautology that merely restates the tool name and HTTP method. It fails to specify what the tool does (e.g., 'Retrieve a high-level summary of analytics metrics') or distinguish it from siblings like aidelly_get_analytics_insights or aidelly_get_analytics_unified.

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 is provided on when to use this tool versus other analytics tools. There is no mention of scenarios appropriate for a summary vs. insights, or any prerequisites like workspace selection.

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

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

The description does not disclose any behavioral traits beyond what annotations already provide (readOnlyHint, idempotentHint, destructiveHint). It adds no context about rate limits, data scope, or required permissions.

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?

While extremely short, the description is underspecified rather than concise. It misses the opportunity to front-load key information, and each character does not earn its place as it adds no 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?

Given the complexity of the tool (6 parameters, 2 required, nested objects), the description is completely inadequate. It does not mention return type, data scope, or how to interpret results, leaving the agent without essential context.

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

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

With only 33% schema description coverage, the description does not compensate. It fails to explain the meaning or usage of parameters like 'from', 'to', 'brand_id', or 'platforms', relying entirely on the schema which is sparse.

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 is merely 'GET /analytics/unified', which restates the tool's name and HTTP method without clarifying what the tool does. It does not differentiate from sibling analytics tools like get_analytics_insights or get_analytics_summary.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions.

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

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

The description adds no behavioral context beyond the annotations. It does not mention return format, pagination, filtering behavior, or any side effects. The annotations already declare read-only and idempotent; the description provides zero additional behavioral disclosure.

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?

While the description is short, it is under-specified rather than concise. 'GET /approvals' is a raw endpoint path, not a meaningful tool description. It omits essential information and fails to earn its place as a useful description.

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

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

The tool has 4 parameters including a nested query object, no output schema, and ambiguous semantics among siblings. The description does not explain what an approval is, what the response includes, how to filter, or when to use this vs list_pending_approvals. It is completely inadequate for correct invocation.

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

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

The description contains no information about any parameters. Schema coverage is only 50% (cursor and brand_id lack descriptions), and this description does nothing to compensate. The 'query' parameter is mentioned in the schema but not in the description, so an agent has no guidance on how to construct a query.

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 'GET /approvals' is essentially an HTTP path that restates the tool name without explaining the action or returned resource. It does not distinguish this from sibling tools like aidelly_list_pending_approvals or aidelly_get_approvals_id, making the purpose ambiguous.

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 is provided about when to use this tool versus alternatives such as aidelly_list_pending_approvals or aidelly_get_approvals_id. There is no mention of intended use cases, prerequisites, or context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds value by noting 'Public API preview', indicating potential instability, and clarifies exactly what setting is read. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core action (GET endpoint) and its purpose. No extraneous words.

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

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

With no output schema, the description does not mention the return format or data shape. While the purpose is clear, the agent lacks information about what the response contains (e.g., a boolean, an object). This is a minimal viable description but incomplete for full automation.

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 50%; the description does not explain parameters beyond the path variable. The schema has descriptions for query and workspace_id, but brand_id lacks any description. The tool description adds no additional parameter semantics, so it meets baseline but does not compensate for gaps.

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

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

The description clearly states the HTTP method (GET), the endpoint path, and explicitly says it reads the 'require_member_approval workspace gate', which is a specific resource. This distinguishes it from the sibling 'aidelly_update_approval_settings' tool.

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

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

The description implicitly tells the agent to use this tool for reading approval settings, and the presence of an update sibling provides context. However, it does not explicitly state when not to use it or mention alternative tools for other approval-related actions.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds no behavioral context beyond the HTTP method. It does not disclose any additional traits like authentication needs, error handling, or rate 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?

The description is extremely concise (one phrase), but it sacrifices informativeness. While it front-loads the HTTP method and path, it could include a brief sentence on what the tool returns or how to use it.

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

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

No output schema exists, so the description should explain the return value. It doesn't. Given the tool has nested input objects and multiple parameters, the description is incomplete for an AI agent to confidently invoke 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 50% (2 of 4 params have descriptions). The tool description provides no parameter information, failing to compensate for the schema gaps. The 'query' and 'workspace_id' params have descriptions in schema, but 'id' and 'brand_id' lack context.

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 'GET /approvals/{id}' conveys it retrieves an approval by ID, but it's minimal and does not distinguish from sibling tools like 'aidelly_get_approvals' (list) or 'aidelly_list_pending_approvals'. The tool name already makes the purpose clear, so the description adds little, but it's not misleading.

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 tool versus alternatives (e.g., when to get a single approval vs listing approvals). Context signals show many related tools, but the description offers no decision support.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only operation. The description adds that it retrieves 'configuration and blocks', which is consistent but adds minimal behavioral context beyond the annotations.

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

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

The description is a single concise sentence with no wasted words. It could benefit from slightly more detail without becoming verbose.

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

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

For a simple read operation with no output schema, the description is adequate but lacks detail about the returned data structure. It provides the basic purpose but not completeness.

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

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

The input schema has 67% description coverage (workspace_id and query described, brand_id missing). The tool description does not add any parameter semantics, failing to compensate for the missing brand_id schema description.

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

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

The description clearly states the tool retrieves the workspace's link-in-bio page configuration and blocks, using a specific verb and resource, distinguishing it from sibling tools like get_brand_profile or get_workspace.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions. The agent must infer usage from context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds no additional behavioral context beyond 'retrieve,' such as expected permissions, rate limits, or response format.

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

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

The description is a single, efficient sentence that front-loads the HTTP method and path. It uses concise language with no superfluous words.

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

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

For a simple retrieval tool with good annotations, the description is adequate. It specifies what is retrieved (brand profile and voice), but lacks details on return structure, which is partially mitigated by the lack of an output schema requirement.

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

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

The input schema has 3 parameters with 67% description coverage. The tool description does not explain any parameter semantics. For example, `brand_id` lacks a description and the description does not clarify its requirement or usage.

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

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

The description clearly states 'retrieve the workspace brand profile, including brand voice,' which specifies the verb and resource. However, it does not explicitly differentiate from sibling tools, though the GET method and readOnlyHint imply a read operation distinct from update tools.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. The usage is implied by the purpose, but there is no mention of when not to use it or what prerequisites might be needed.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it is a safe read operation. The description adds no additional behavioral context (e.g., permission needs, return format), but since annotations cover safety, a baseline score of 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?

The description is extremely short (one line) but lacks substance. It is under-specified rather than concise, omitting essential information about the tool's purpose and behavior.

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

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

Despite good annotations, the description does not explain the tool's return value, the meaning of 'brand settings context', or the purpose of the 'brand_id' parameter. No output schema exists, leaving agents with limited understanding of what the tool returns.

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 67% (two of three parameters have descriptions). The tool's description does not mention any parameters or add meaning beyond what the schema provides. The schema already documents 'query' and 'workspace_id' adequately. Baseline 3 is appropriate.

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

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

The description is merely the HTTP method and endpoint 'GET /brand/settings-context', which does not explain what the tool does. The title from annotations ('Get Brand Settings Context') gives some clue but the description itself is vague, not specifying what 'brand settings context' means or what the tool retrieves.

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 is provided on when to use this tool versus the many sibling tools. The description lacks context about typical use cases, prerequisites, or alternatives.

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