aidelly

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

The description adds genuinely useful operational context beyond the annotations (workspace settings permission required, 50-document cap, HTML pages rejected with 415, text is extracted/indexed). However, it states the call is 'Retry-safe: a repeat call with the same idempotency_key returns the original result,' which asserts idempotent behavior while the annotation declares idempotentHint=false — a direct conflict on the retry semantics an agent uses to decide whether re-calling is safe.

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

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

Four dense sentences, front-loaded with purpose and source options, then constraints, then operational behavior. Each sentence carries distinct information (format limits, XOR rule, indexing target, permission/quota, retry semantics) with no filler.

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

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

For an 11-parameter create tool with no output schema, the description covers ingestion format, constraints, permissions, quota, and error behavior well. It omits what a successful call returns (e.g., a document id to feed into aidelly_get_brain_document), the only notable gap given no output schema exists.

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

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

Schema description coverage is 45% across 11 parameters, so the description must compensate. It contributes the mutual-exclusivity rule ('exactly one of text or source_url'), the optional title/document_type/tags, and the idempotency_key retry semantics, but leaves body, query, brand_id, description and workspace_id partly unexplained, so it only partially fills the coverage 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?

States a specific verb+resource ('Add a reference document to the workspace Brain') and names both ingest paths (pasted text or source_url file). It also distinguishes itself from sibling document tools by explaining that the text is extracted and indexed for aidelly_search_brain, so an agent knows this feeds the search corpus rather than, say, the upload-URL flow.

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

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

Gives clear when-to-use rules: 'Supply exactly one of text or source_url' and 'web pages return 415, so send their text instead,' plus the retry condition. It stops short of contrasting with the closest siblings (aidelly_add_brain_entry vs. create_brain_document_upload_url), so it doesn't reach full alternative routing.

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

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

Annotations only say not-read-only, open-world, non-destructive; the description supplies the operational context they omit: workspace-settings permission requirement, agency-owner/manage_agency_brain requirement for scope=agency, queued/pin_applied/memory_id return semantics, delayed embeddings, and idempotency_key reuse on retries. This is far beyond what structured fields provide.

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

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

Front-loaded with purpose and trigger, then permission and edge-case behavior in descending priority. Most sentences earn their place, though the enumerated knowledge types largely restate the `type` enum and could be trimmed.

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 14-parameter mutation tool with no output schema, the description compensates well by explaining the response flags (queued, pin_applied, memory_id null for agency) and permission prerequisites. Remaining incompleteness is limited to the undocumented secondary 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 coverage is only 36% across 14 parameters, so the description must carry weight. It clarifies the trickiest ones (idempotency_key retry reuse, scope=agency semantics, pinned being unsupported for agency), but many parameters (importance, valid_until, tags, platforms, brand_id, content limits) remain undocumented in both the schema and the description.

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

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

States a specific verb and resource ('Add knowledge to the selected workspace Brain') plus the trigger ('when the user asks to remember or save it'). The enumerated knowledge types and the distinction from 'confirmed knowledge rather than invented facts or transient drafts' separate it cleanly from siblings like aidelly_add_brain_document and aidelly_update_brain_entry.

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

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

Gives explicit when (user asks to remember/save confirmed brand facts), when-not (invented facts, transient drafts), a de-duplication alternative ('Search first to avoid duplicates'), and a narrow conditional path for scope=agency with its own permission preconditions. Routing guidance is complete enough to act on without opening other schemas.

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=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. However, the description adds essentially nothing beyond the title: it does not explain what happens on a duplicate domain, how the required idempotency_key affects retry safety (notably the annotations declare idempotentHint=false despite a required idempotency key), or whether a missing workspace_id causes an error.

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

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

A single front-loaded sentence with zero filler, which is efficient and easy to scan. It is arguably too terse for a seven-parameter mutation, but on the conciseness dimension itself there is nothing to trim.

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

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

For a 7-parameter, non-idempotent, open-world mutation with a nested object override, low schema coverage, and no output schema, the description is far too thin. It omits duplicate-handling behavior, workspace/brand scoping rules, idempotency-key usage, and the purpose of the body/query override parameters, leaving the agent to guess.

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 43%, so the description must compensate and it does not. Only 'root domain' hints at the expected format of the required `domain` parameter; the required `idempotency_key` semantics, the `brand_id` vs `workspace_id` relationship, and `display_name` usage are left entirely to the schema (or 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 gives a specific verb and resource ('Register a competitor root domain to track'), which is far more precise than the bare title 'Add Competitor' and clearly pairs with the read-only sibling aidelly_list_competitors. It stops short of explicitly naming that sibling or stating what makes this distinct from other add_* tools, so it lands at a clear-but-undifferentiated 4.

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 when-to-use guidance, no prerequisites (e.g. workspace must exist, brand must be set up), and no mention of alternatives such as aidelly_list_competitors for checking whether a competitor is already tracked. The only usage signal is the weak implication that this is for adding a tracked domain.

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 the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the bar is lower. The description adds the 'to track' intent, but it does not explain the required idempotency_key, how duplicate handles are handled, or what happens to an existing creator on re-registration. 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though arguably too sparse for an 8-parameter mutation tool.

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

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

For an 8-parameter, 3-required create tool with low schema coverage and no output schema, the description is too thin. It omits idempotency semantics, workspace scoping, and the optional brand_id/display_name fields an agent would need to populate a correct call.

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

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

Schema description coverage is only 38% across 8 parameters, so the description must compensate but does not. It implicitly covers only handle and platform, leaving brand_id, display_name, idempotency_key, workspace_id, body, and query unexplained in prose.

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

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

States a specific verb (register) and resource (creator handle) scoped to a platform, which is more informative than the title 'Add Creator'. However, it does not distinguish itself from the adjacent sibling aidelly_add_competitor, which follows the same 'register a tracked entity' pattern, so an agent could confuse the two.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as aidelly_list_creators or aidelly_add_competitor. The requirement that workspace_id is needed for create operations is left entirely to the schema and never surfaced here.

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 (readOnly=false, destructive=false, openWorld=true, idempotent=false) cover the safety profile, and the description adds genuinely new behavioral context: append-to-end ordering, scheduling to next available slots, and the idempotency_key retry contract. It stops short of describing batch/partial-failure behavior for the items array or auth requirements, so not a 5.

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

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

Three short sentences, front-loaded with purpose, then effect, then retry contract. No filler and every sentence adds information an agent can act on.

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

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

For a 7-parameter mutation tool with nested items and no output schema, the definition covers purpose, side effect, and idempotency but omits multi-item failure handling, error/return shape, and the workspace/brand scoping that the siblings imply. Adequate but with notable gaps.

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

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

Schema coverage is only 43% (below the 50% threshold), so the description should compensate. It does explain the idempotency_key semantics ('a repeat call with the same idempotency_key returns the original result'), which is valuable since that required parameter has no schema description, but leaves `id`, `brand_id`, `workspace_id`, `body`, and `query` essentially unexplained. Partial compensation only.

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

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

Specific verb and resource: 'Add content items to the end of a distribution queue,' which is clearly distinct from the create-style siblings (create_queue, bulk_create_posts, create_scheduled_post). It does not, however, explicitly name or contrast those alternatives, so it stays at 4 rather than 5.

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

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

The description explains the consequential effect ('items publish in the queue's next available time slots') which implies the use case of scheduling existing content into a queue. But it gives no explicit when-not guidance, no prerequisites, and no pointer to the sibling (create_scheduled_post, bulk_create_posts) an agent might pick instead.

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

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

Goes well beyond the annotations: discloses that archiving unpins the entry, that nothing is deleted, the workspace settings permission requirement, the special agency-entry permission path and memory_id null return, the 409 BRAIN_ENTRY_DERIVED failure for derived entries, and idempotency-key reuse on retries. This is unusually rich behavioral context 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?

Front-loads the core action and the archived=true/false mapping in the first sentence, then layers prerequisites and error behavior. Dense but every clause carries operational information; no filler.

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

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

With no output schema, the description still covers return-relevant behavior (memory_id null, 409 code) and permission prerequisites, which is enough for an agent to call it correctly. Minor gap: no mention of what a successful archive returns or whether workspace_id is required for this operation.

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%, and the description adds meaning mainly for the id parameter (use entry.id when memory_id is null) and restates archived semantics already in the schema. brand_id, workspace_id, body, and query remain undocumented, so it only partially compensates for the coverage 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?

States a specific verb pair (archive/restore) plus the resource (Brain entry) and the exact flag semantics (archived=true/false). It also distinguishes the operation from deletion ('nothing is deleted'), which separates it from the sibling delete_brain_document.

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

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

Explicitly frames the intent ('Intended for knowledge the user asked to retire') and clarifies the reversible nature, so an agent knows when this is preferable to deletion. It does not name a sibling alternative (e.g. update_brain_entry) for non-retirement edits, so it falls short of a 5.

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

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

Discloses behavior the annotations do not: 201 vs 207 status semantics, the per-item results array with index/status, the distinction between acceptance and delivery, per-post rate-limit accounting, and all-or-nothing preflight rejection when the daily scheduling limit would be exceeded. The idempotentHint=false annotation is not contradicted — the description correctly scopes idempotency to repeat calls carrying the same key.

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

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

Front-loaded with purpose, then shape reference, then return contract, then cost model, then platform caveat, then retry semantics. Every sentence delivers a distinct operational fact; nothing is padding.

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

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

For a mutation tool with no output schema, 6 parameters, and deep nested item objects, the description covers the response contract and failure modes well. Minor gaps: it doesn't clarify that scheduled_at is per-item optional despite the tool being framed as scheduling, and it doesn't mention what happens to a partially failed 207 batch on retry beyond the idempotency note.

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%, and the description fills the most important gap by explaining idempotency_key's retry contract, which the schema only defines as a pattern. It also restates the 50-item cap and the LinkedIn document constraints (redundant with the schema media description). It says nothing about brand_id, workspace_id, or the body/query override 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?

Opens with a specific verb, resource, and scope: 'Create up to 50 scheduled posts in one call.' It also distinguishes itself from the single-post sibling by noting each item 'takes the same shape as aidelly_create_post', so an agent knows the relationship without opening either schema.

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

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

Gives a concrete selection signal — batches save round trips but not quota, since rate limit is charged per post — which tells the agent when batching is and isn't worth it. It also covers the retry case via idempotency_key. It stops short of explicitly saying 'use aidelly_create_post for a single post,' so the alternative is implied rather than named.

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

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

Annotations cover the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=true), and the description adds real behavioral context beyond them: the resulting state (status=canceled, record kept), the 409 rejection paths, the deliberate non-effect on pending auto-recycle entries, and retry semantics. The retry-safety claim is conditioned on the idempotency_key, which qualifies rather than flatly contradicts idempotentHint=false, but the tension means it is not a clean 5.

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

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

Four tight sentences, each carrying distinct information: effect, rejection conditions, sibling-tool boundary, and retry behavior. The primary outcome is front-loaded with zero filler.

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

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

With no output schema, the description must carry behavior, and it does: state change, error path, side-effect scope, and retry semantics. Minor gaps remain, such as whether workspace_id is required for this mutating call given the schema's 'required when creating content' note, and what the response body contains.

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 explains the meaning of the most consequential parameter, idempotency_key (same key returns the original result), but says nothing about brand_id, workspace_id, or the body/query overrides, and the target post id is only referenced anaphorically as 'the post'. At mid coverage this is adequate but not compensating.

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

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

States a specific verb+resource (cancel a post) and the exact effect: the post will not publish, status becomes canceled, record retained. It explicitly distinguishes itself from aidelly_cancel_scheduled_post, which also cancels pending auto-recycle entries, so an agent can pick correctly without opening either schema.

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

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

Gives explicit when-not conditions (posts already completed, failed, or canceled are rejected with 409) and names the alternative tool with the condition that selects it (aidelly_cancel_scheduled_post also cancels pending auto-recycle entries). Nothing about routing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it discloses that records are retained and only statuses change to canceled, that dependent auto-recycle entries are affected, the auth requirement, and the concrete retry mechanism (same idempotency_key returns the original result). This meaningfully clarifies what 'destructive' does and does not mean here.

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

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

Four tight sentences, each carrying unique information: scope, side effects, auth, alternative tool, and retry behavior. The cascade scope is front-loaded and there is no filler.

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

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

For a mutation tool with no output schema and a sparse parameter schema, this covers effect, retention, auth, alternative, and idempotency. The only missing piece is any indication of the returned payload outside the retry case, which is a minor gap given no output schema exists.

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

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

Schema coverage is only 40%, so the description must carry weight; it explains idempotency_key semantics and the workspace_id/key requirement, covering two of the three undocumented parameters. It says nothing about the `id` being the post UUID, `brand_id`, or the `query` override object, so gaps remain.

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

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

States a specific verb (Cancel) and resource (scheduled calendar post) plus the cascade scope (pending auto-recycle entries / reposts and reshares). It explicitly distinguishes itself from the near-identical sibling aidelly_cancel_post by contrast, so the agent can pick correctly without opening either schema.

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

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

Names the alternative (aidelly_cancel_post cancels only the single post), which implies this tool is the cascade variant, and states the auth precondition (workspace-scoped key or workspace_id). It stops short of an explicit 'use this when / avoid when' sentence, so the selection rule is strongly implied rather than spelled out.

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

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

Adds real behavior beyond the annotations: text extraction and indexing side effects, one document per upload_id, a 2-hour expiry on upload_id, and a workspace-settings permission requirement. The one tension is 'Retry-safe with the same idempotency_key' against idempotentHint=false; this is arguably conditional idempotency via the key rather than a flat contradiction, but it is worth flagging as imprecise.

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

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

Four tight sentences, front-loaded with the workflow anchor, then optional fields, then the scoping constraints (expiry, client visibility, permissions) and retry semantics. No sentence is filler and each adds an operational fact.

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 10-parameter mutation with no output schema, the description covers the prerequisite, side effects, TTL, permissions and retry behavior well; return values need not be explained without an output schema. The remaining gap is undocumented non-required parameters such as brand_id and the body/query overrides.

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 30% across 10 parameters, so the description should compensate more than it does. It calls out the optional title, description, document_type and tags, but says nothing about brand_id, body, query, or the idempotency_key format, leaving several parameters to the 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?

States a specific verb and resource ('Finish a Brain document file upload') and immediately anchors it to the sibling step 'aidelly_create_brain_document_upload_url'. It also names the downstream effect (indexed for aidelly_search_brain), so an agent can distinguish it from aidelly_add_brain_document and the URL-creation sibling.

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

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

Gives the exact precondition ('after the file was PUT to the upload_url from aidelly_create_brain_document_upload_url') and a usage constraint ('Hidden from browser-sandboxed chat clients'), which is strong context. It stops short of naming an explicit alternative or when-not-to-use case (e.g. small inline documents via aidelly_add_brain_document), so it lands just under full marks.

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

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

Goes well beyond the annotations, which only say it is a non-read-only, non-destructive, open-world, non-idempotent operation. The description adds the return contract (signed upload_url plus a content-type header to PUT, an upload_id valid for 2 hours), the permission requirement, and retry semantics via idempotency_key — useful nuance given idempotentHint=false.

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

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

Three dense sentences ordered by importance: what it does and returns, the follow-up call, then eligibility and permissions. No filler, and the operational constraints are front-loaded.

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

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

No output schema exists, yet the description fully specifies the return shape and lifetime, the downstream call, the client-eligibility constraint, and the permission prerequisite — everything an agent needs to invoke this correctly or route to aidelly_add_brain_document.

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

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

Schema coverage is only 50%, and the description compensates by naming the allowed file types (PDF, DOCX, TXT, Markdown), the 10 MB cap, and the meaning/behavior of idempotency_key. It does not mention brand_id or explain the body/query override parameters, so a small gap remains.

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?

Precise verb+resource: 'Start a Brain document file upload', with accepted formats and size cap stated. It also distinguishes itself from aidelly_add_brain_document and points forward to aidelly_complete_brain_document_upload, so an agent can place it in the right step of the flow without opening any schema.

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

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

Explicit when-to-use and when-not-to-use: 'Works only for clients with direct network access to Supabase storage, such as Claude Code or a local CLI; the hosted server hides it from browser-sandboxed chat clients, which use aidelly_add_brain_document instead.' It also states the required permission and the mandatory follow-up call.

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

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

Adds real context beyond the annotations: asynchronous execution, workspace approval rules gating publishability, the returned job id, and the retry-safety contract tied to idempotency_key. The retry-safe claim sits in mild tension with idempotentHint=false, but it is explicitly conditioned on reusing the same idempotency_key, so it is reconcilable rather than contradictory. Still missing is what happens on partial failure of a 200-post batch.

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

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

Four tight sentences, front-loaded with what the tool creates before moving to rules, return value, and retry behavior. No filler; every clause carries operational information. Slightly dense but appropriately sized for a multi-object async job tool.

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

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

For an async, nested-object tool with 6 params and no output schema, the description covers scope, per-item requirements, approval gating, the polling counterpart, and retry semantics. It does not explain batch-level failure behavior, validation failures, or when workspace_id/brand_id are required, which the schema only hints at.

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 coverage at 50%, the description compensates by explaining the posts array semantics (platform, caption, scheduledAt with offset, destination, optional media) and the idempotency_key retry contract, which the schema states only via pattern/example. It leaves the generic body/query override objects and brand_id undocumented in both places.

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

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

Specific verb+resource+scope: 'Create an asynchronous job to schedule 1-200 supplied social posts in the selected workspace', with per-post contents enumerated. It clearly states the deliverable (a job id) and names the companion tool aidelly_get_bulk_fill_job. However, it never distinguishes itself from the very similar sibling aidelly_bulk_create_posts or aidelly_create_scheduled_post, so an agent cannot pick between them from the text alone.

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

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

Usage is only implied by the 1-200 post scope and the async framing; there is no explicit when-to-use statement and no when-not/exclusion. The only routing guidance is downstream (call aidelly_get_bulk_fill_job to poll), which helps but does not tell the agent when this tool beats aidelly_bulk_create_posts or aidelly_create_post.

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

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

Discloses a high-value trait the annotations don't cover: the raw access token is returned only once and cannot be re-read, warning the agent to surface it immediately. It also explains retry/dedup semantics via idempotency_key; note the mild tension with idempotentHint=false, though keyed dedup is a distinct concept and not a true 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?

Three tight sentences: purpose first, then the critical token-once warning, then retry behavior. No filler, and the most operationally important detail (token shown once) 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?

No output schema exists, and the description covers the one return value that matters (the one-time raw token). Annotations already carry the safety profile (destructiveHint=false, openWorldHint=true). It stops short of describing the portal URL or link metadata, a minor gap.

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

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

With 75% schema coverage, most params (label, expires_at, client_email, workspace_id) are already documented in the schema, so the baseline is 3. The description adds genuine meaning for idempotency_key — that a repeat call with the same key returns the original result — which the schema itself does not explain.

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

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

States a specific verb+resource ("Create a magic-link review portal") and adds scope ("where a client reviews workspace content without an Aidelly account"), which cleanly distinguishes it from the many sibling create_*_link tools (report_link, connect_link, short_link). An agent can select it without opening the schema.

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

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

The description conveys the intended context (client review without an account) but never names alternatives or a when-not condition, e.g. pointing to aidelly_revoke_client_review_link for cleanup or aidelly_list_client_review_links for retrieval. Usage is implied rather than stated.

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

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

The annotations already disclose that this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds no behavioral context beyond the purpose, such as authentication requirements, rate limits, or what happens when a link is created. It does not contradict the annotations, but it also does not enrich them.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately concise for a short purpose statement, though its brevity contributes to the gaps in usage and parameter guidance.

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

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

For a 7-parameter mutation tool with nested objects and no output schema, the description is far too thin. It states the purpose but omits usage guidance, parameter semantics, and behavioral details beyond what the annotations already provide. An agent would need to rely heavily on the schema and sibling context to invoke it correctly.

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

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

Schema description coverage is 57%, and the description only hints at the workspace_id parameter by saying 'for the workspace.' It does not explain the required idempotency_key, the optional password, title, brand_id, or the sparse body/query override objects. With moderate schema coverage, the description should compensate for undocumented parameters but fails to do so.

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

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

The description states a specific verb ('Create') and resource ('OAuth connect link'), making the core action clear. It also scopes the operation to the workspace. However, it does not explicitly differentiate this link from sibling link-creation tools like create_short_link or create_client_review_link, nor does it explain what a 'connect link' is for beyond the OAuth label.

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 such as create_client_review_link, create_report_link, or create_short_link. It also omits prerequisites or conditions, such as whether a workspace or brand must already exist. The only implied context is that it creates an OAuth connect link for a workspace.

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

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

Annotations only give the safety profile (readOnly=false, destructive=false, openWorld=true). The description adds real behavioral context beyond them: active rules keep generating/scheduling/publishing per approval settings, the call returns the saved rule, and repeat calls with the same idempotency_key are deduped. Note the tension with idempotentHint=false: the retry-safe claim is scoped to the key, so it is a nuance rather than a hard 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?

The core action is front-loaded and every clause carries information (scope, side effects, return value, retry semantics). It is a touch dense but contains no filler sentences.

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 'returns the saved rule' note is a useful surrogate. However, for a create tool whose primary input is a rule configuration, the description never explains what the body/config actually contains, and brand_id is unexplained, leaving the agent unable to fully construct the call.

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

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

Schema coverage is 60% (baseline 3). The description adds meaning for 'body' (holds the rule configuration) and for idempotency_key (retry semantics), but brand_id is undocumented anywhere and body is described circularly as an 'override for sparse parameter schemas,' so it does not compensate for the uncovered params.

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

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

States a specific verb and resource ('Create a content automation rule') and scopes it to two rule types (scheduled content generation, YouTube repurposing). This distinguishes it from one-off job siblings like aidelly_create_repurpose_job, but it doesn't explicitly name the contrast, so it stops short of a 5.

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

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

The mention of the supported rule types implies when the tool is appropriate (scheduled generation or YT repurposing), but there is no explicit when-to-use/when-not guidance and no routing versus update_content_automation, trigger_content_automation, or create_repurpose_job. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact — 'Saving a preset publishes nothing' — which guards against the reasonable misreading that fanning a post out across channels could trigger publishing. It does not discuss idempotency_key behavior despite the mutation.

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

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

Two sentences, front-loaded with the action and resource, then the clarifying semantic. Every clause carries weight with no filler or restatement of the title.

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

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

For an 8-parameter nested creation tool with no output schema, the description covers what is created and the key non-obvious behavior (no publishing). It stops short of noting the required idempotency key or workspace scoping, though those are partly documented in the schema itself.

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 documents name, channels, transform fields, defaults, and workspace_id reasonably well. The description clarifies the concept of 'channels with per-platform transformations' at a domain level but adds no field-level syntax or format guidance, so it hovers at the baseline for a well-covered schema.

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

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

States a specific verb+resource ('Create a destination preset') and then defines what the resource actually is — a saved set of channels with per-platform transformations used for cross-channel fan-out. This is markedly more informative than the bare title and lets an agent distinguish it from siblings like aidelly_preview_destination_preset or aidelly_create_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?

The fan-out sentence implies the purpose context, but there is no explicit when-to-use, when-not, or named alternative (e.g., preview vs. create vs. apply to a post). The agent must infer that this is the persistence step rather than the execution step.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely non-derivable behavior: drafting never publishes, a planned date does not schedule, and repeat calls with the same idempotency_key return the original result. The idempotency claim sits slightly awkwardly against idempotentHint=false, but that annotation describes keyless repetition, so this is context rather than a 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?

Three tight sentences, each carrying distinct payload: what a draft is, the platform constraint, the non-scheduling caveat, and retry safety. The defining behavior is front-loaded and nothing is padding.

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

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

For a 12-parameter mutation tool with no output schema, the description covers the high-risk misconceptions (publishing, scheduling, duplicate creation on retry). It does not mention the workspace_id requirement for content creation, which the schema handles, so the gap is minor.

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

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

Schema coverage is 83%, which sets a baseline of 3, but the description adds meaning the schema lacks — the platform/platforms either-or requirement and the non-scheduling semantics of draft_planned_for are reinforced, and the required idempotency_key is explained behaviorally, which the schema documents only with an example and pattern.

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

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

States a specific verb and resource ('Create a draft') and immediately defines the resource's defining behavior: 'work-in-progress content that is saved but never publishes.' That clause functionally separates it from aidelly_create_post and aidelly_create_scheduled_post without the agent needing to open their schemas.

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

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

Gives a real precondition ('Requires platform or a non-empty platforms array') and clarifies the trap that draft_planned_for 'is a planning date only and schedules nothing.' It does not explicitly name the sibling to use instead when the intent is to publish (create_post / create_scheduled_post), which is what keeps it out of 5 territory.

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=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds essentially nothing beyond that safety profile -- notably it never explains that a mandatory idempotency_key exists (despite idempotentHint=false) or what happens on duplicate submission.

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

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

A single well-formed sentence with no filler and the core action front-loaded. It is efficient, though arguably too short for a 10-parameter mutation tool.

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

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

For a creation tool with 10 parameters, nested free-form objects, and a required idempotency_key, the description omits prerequisites, workspace scoping, and any behavior on retries. With annotations covering only the safety profile, the definition leaves significant gaps.

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

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

Schema description coverage is only 70% across 10 parameters, and the description merely restates the 'initial body or topic' idea that the schema already documents via initial_body and seed_topic. It does not compensate for the undocumented remainder (e.g. brand_id, tags, query overrides).

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

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

States a specific verb (Create) and resource (idea on the workspace's idea board) with the seeding option, which is enough to separate it from create_draft or create_post. It does not explicitly contrast with sibling creation tools, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no mention of the required idempotency_key, no note that workspace_id is required for content creation, and no routing to alternatives like create_draft or create_post. An agent must infer all of this from the schema.

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

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

With annotations present, the description still adds meaningful context beyond them: rules are enabled by default, enabled=false saves an inactive rule, the default 'contains' match, and retry-safety via idempotency_key. Auth/permission and rate-limit behavior are not mentioned. The retry-safe claim sits in mild tension with idempotentHint=false, though it clarifies the key-based dedupe mechanism rather than misleading the agent.

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

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

Front-loads purpose, then required params, then runtime behavior and return/retry semantics. Every sentence does work, though 'Returns the created rule' is largely implied for a create tool and the paragraph is dense.

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 15-parameter tool with nested objects and no output schema, the description usefully states the return value and idempotency contract. But it omits semantics for most non-required parameters (guardrails, responseMode, triggerEvent, campaignDurationDays) that the sparse schema does not fill in, leaving an agent under-informed for a non-trivial configuration call.

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

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

Schema coverage is low (40%) across 15 parameters, so the description would need to compensate. It adds real semantics for three of them (platformAccountId source, keyword required for comment triggers, enabled default) but leaves guardrails, responseMode, triggerEvent, matchType, campaignDurationDays, brand_id, platform, and workspace_id undocumented, so coverage remains partial.

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

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

States a specific verb and resource ('Create an automatic reply rule') and scopes it to connected Instagram accounts or Facebook Pages. It clearly distinguishes the artifact (an inbox auto-reply rule) but never names a sibling such as aidelly_update_inbox_automation or aidelly_create_content_automation, so differentiation leans on the 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?

It conveys enabling conditions (requires platformAccountId and message; keyword for comment triggers) and default behavior, which implies when to use it. However, it gives no explicit when-to-use vs alternatives or when-not guidance (e.g., update vs create, template vs ai reply).

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

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

Adds real context beyond the annotations: that the client must perform an HTTP PUT of raw bytes, that the tool is hidden from sandboxed clients, and that retries with the same idempotency_key return the original result. The retry-safety claim sits in mild tension with idempotentHint=false, so this is not a clean 5, but the disclosure is otherwise strong and not a flat 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?

Five sentences, each load-bearing: purpose first, then eligibility, then the alternative, then retry semantics. No filler or restatement of the name.

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

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

With no output schema, the agent still learns what is created, how the returned URL is used (PUT raw bytes), who may call it, and idempotency behavior. It stops short of describing the response shape or URL lifetime and does not fill the low-coverage parameter gaps, so it is not fully complete for a 9-parameter 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?

Schema description coverage is only 44%, so the description is expected to compensate. It only references idempotency_key in passing and says nothing about folder, brand_id, content_type, file_name, or how workspace_id interacts with the required-args rule, leaving most parameters underexplained.

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

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

States a specific compound verb+resource: creating a media record plus a signed Supabase Storage upload URL. It immediately differentiates itself from the sibling aidelly_upload_media by name, so an agent can route between them without opening either schema.

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

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

Gives an explicit eligibility condition (clients with direct network access to Supabase storage, e.g. Claude Code or a local CLI) and an explicit when-not (browser-sandboxed chat clients block egress), then names the alternative tool for that case. This is exactly the when/when-not/alternative pattern.

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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds useful context that this writes to a platform gallery outside the post pipeline and that only google_business is currently wired, but says nothing about auth requirements, rate limits, or what the destructive PROFILE/LOGO/COVER replacements do (that detail lives only in the schema).

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

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

One compact sentence, front-loaded with the action and resource, with the parenthetical scope qualifier and the platform constraint appended. Nothing is wasted and nothing important is buried.

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

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

For an 11-parameter mutation tool with nested objects and no output schema, the definition leans heavily on the schema and annotations. It omits what a successful call returns (photo identifier, URL) and any note that identity categories overwrite existing assets, so it is adequate but leaves real gaps.

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

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

Schema description coverage is 73% and 11 parameters exist; the schema documents category, platform, account_id, source_url, description and idempotency_key well. The description contributes no parameter meaning beyond restating the platform restriction already in the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Upload a photo to a connected platform's media gallery") and scopes it with "(separate from posts)," which cleanly separates it from aidelly_create_post. It does not, however, differentiate itself from the sibling aidelly_upload_media, leaving one plausible alternative unaddressed.

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?

"Separate from posts" gives implied usage guidance, and "Today only google_business is wired" sets an availability constraint. But there is no explicit when-to-use/when-not statement, and the closest alternative (aidelly_upload_media) is never named or excluded.

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?

Well beyond the annotations, it explains that HTTP 201/ok=true means accepted rather than delivered, that completion must be confirmed through aidelly_get_post with a non-null provider_post_id, and that a repeat call with the same idempotency_key returns the original result. That is genuinely useful async/verification context the annotations cannot express. There is mild tension with idempotentHint=false (which reads as 'retrying may duplicate'), but the description's statement is conditional on reusing the key, so it clarifies rather than misleads.

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

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

Five sentences, each doing distinct work: purpose, async acceptance semantics, Pinterest board sourcing, LinkedIn document constraints, and retry behavior. Purpose is front-loaded, there is no filler, and the length is proportionate to a 13-parameter tool with deep nested objects.

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

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

For a complex mutation with no output schema, it covers the critical unknowns: the operation is asynchronous, success means queued not delivered, and how to verify delivery. Remaining gaps are minor but real: the required content.text field is only implied, and the scheduled path's interaction with timezone and idempotency is left entirely to the schema.

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

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

Schema coverage is 54%, so the description needs to carry some weight, and it does for idempotency_key (retry semantics), content.platform_specific.board_id, and media[].type = document. Several parameters remain undocumented in both places (scheduled_at, timezone, brand_id, metadata), and the description says nothing about how scheduling interacts with idempotency or the workspace/account targeting parameters.

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

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

The first sentence gives a specific verb and resource ("Accept a post ... on a connected account") and names the two modes it covers, immediate publish and future scheduling. An agent knows exactly what the tool produces. It does not, however, distinguish itself from close siblings such as aidelly_create_scheduled_post, aidelly_bulk_create_posts, or aidelly_create_draft, even though the scheduling mode overlaps with one of them.

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

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

It implies when to use it (publish now, or pass a scheduled time) and supplies real prerequisites: an idempotency_key for retries, a Pinterest board id from aidelly_list_pinterest_boards, and a single PDF for LinkedIn documents. What is missing is routing: with aidelly_create_scheduled_post and aidelly_bulk_create_posts in the sibling set, the description never says which of them to prefer or when this tool is the wrong choice.

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=false, destructiveHint=false, openWorldHint=true, idempotentHint=false, so the safety profile is covered. The description adds useful behavior (automatic @mention parsing, root-anchored replies) but says nothing about what the required idempotency_key does or what a replayed request returns — notable given the idempotentHint=false 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?

Three short, front-loaded sentences with no filler; the purpose comes first, then the required field, then the reply rule. 'Text body is required' mildly restates the schema's required list but earns its place as emphasis for a mutation.

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 with no output schema, the description covers the core call pattern but omits how the required idempotency_key should be formed and whether workspace_id is mandatory for comment creation (the schema says it's required when creating content). Those are material gaps for a mutation 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?

Schema coverage is 63% and the description clarifies the two hardest parameters: it confirms `text` is required and sharpens `parent_comment_id` into 'pointing to the root comment,' implying flat threading. It leaves `idempotency_key`, `brand_id`, and `id` unexplained, so it only partly compensates for the coverage 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?

States a specific verb and resource: 'Create a comment on a post.' An agent immediately knows the operation. It does not, however, name or contrast with the evident siblings update_post_comment, delete_post_comment, or list_post_comments, so differentiation is left to 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?

It gives one concrete usage rule — replies must set parent_comment_id to the root comment — which is real guidance about when/how to use the tool. There is no explicit when-not-to-use clause and no pointer to the sibling comment tools for reading, editing, or deleting.

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=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond the annotations: creating the queue triggers no publishing. It doesn't cover auth requirements or return behavior, so it stops short of 5.

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

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

Two tight sentences, front-loaded with the core action and followed immediately by the crucial non-effect. Every clause carries information; no filler.

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

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

For a 9-parameter create tool with annotations but no output schema, the description covers purpose, the sibling relationship and the key side-effect. Gaps remain around required inputs (workspace_id for creation, slots structure) but the structured fields largely carry those, so it is close to complete.

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

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

Schema coverage is 78%, with the schema documenting name, slots, timezone, channels and workspace_id. The description only echoes the recurring weekly slot concept and adds no syntax or format detail, so it does not meaningfully extend the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a content distribution queue') plus its defining characteristic ('recurring weekly time slots'). It also distinguishes itself from the sibling aidelly_add_queue_items by naming it and clarifying that creation alone publishes nothing, so an agent can route correctly.

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

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

Explains the workflow relationship: content added via aidelly_add_queue_items publishes in the slots, while creating the queue publishes nothing. This gives clear context for when to use it, though it doesn't state explicit exclusions or prerequisites (e.g. required workspace_id when creating content).

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 real behavioral context beyond the annotations: the snapshot is built synchronously (so the call blocks until analytics are ready) and the data source is the workspace's connected accounts. However, its explicit claim that a repeat call with the same idempotency_key returns the original result describes idempotent semantics, which conflicts with the annotation idempotentHint=false, leaving the agent unsure whether duplicate calls are safe. The core create/read profile (readOnlyHint=false) is consistent, but the idempotency claim is a genuine conflict.

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

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

Two dense sentences with zero filler, front-loaded with the action and resource before the mechanism and retry caveat. Nothing in the text is redundant with the title or annotations.

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

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

For a 12-parameter mutating tool with no output schema, the description covers the core purpose, the blocking snapshot build, and retry behavior, which is enough to call it. It is incomplete on the optional shaping parameters (sections, templateId, commentary) and on the workspace requirement for content creation, both of which are only partially covered by the 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 only 25% across 12 parameters. The description explains the date-range inputs and the meaning of idempotency_key ('same key returns original result'), but says nothing about brand_id, sections, commentary, templateId, includeComparison, workspace_id, or the opaque body/query override objects, so most parameters remain semantically 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 states a specific verb and resource ('Create a report') and adds the mechanism ('synchronously build its analytics snapshot from the workspace's connected accounts'), so the agent knows this is a report-creation tool with an immediate snapshot build. It does not, however, distinguish itself from close siblings such as aidelly_create_report_link, aidelly_create_report_schedule, or aidelly_get_report, so sibling differentiation is absent.

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

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

Usage context is implied: it is for producing a report over a date range using the workspace's connected accounts, and the retry-safe note tells the agent how to re-issue a call. There is no explicit guidance on when to prefer this over create_report_schedule (recurring), create_report_link (sharing), or when not to call it, so routing is left to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=true), and the description adds real value on top: the retry-safe behavior tied to idempotency_key and the mode-dependent refresh semantics. It does not describe the returned artifact, but it meaningfully supplements the annotations rather than repeating them.

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

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

Three tight sentences, each earning its place: purpose and modes first, the revoke alternative second, retry semantics last. No filler or redundancy.

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

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

For an 11-parameter, nested-object, no-output-schema tool, the description covers purpose, mode selection, revocation path, and idempotency. It omits what the call returns (presumably the link URL), which would help since no output schema exists.

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

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

Schema coverage is 82%, so the schema already documents nearly every parameter (mode, cadence, password, expires_at, workspace_id). The description echoes the mode/cadence relationship without adding format or syntax detail beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb ('Create') and resource ('shareable link to a workspace report') and clarifies the two modes (snapshot vs live). It distinguishes itself from link-creating siblings (create_short_link, create_client_review_link) by resource scope, though it never names them explicitly.

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

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

Gives clear usage context: the snapshot-vs-live choice is explained, and it names aidelly_revoke_report_link as the tool that disables the link. It does not, however, tell the agent when to prefer this over the other link-creation siblings.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive write. The description adds a genuinely useful operational constraint beyond that — a soft cap of 10 active schedules per workspace — which is exactly the kind of quota/rate-limit context the rubric credits. It still omits permission requirements and what happens when the cap is exceeded (rejected vs. soft-warned).

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

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

Two short sentences, zero filler, and the core action is front-loaded before the quota caveat. Nothing could be removed without losing information.

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

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

For a 10-parameter mutation tool with nested objects, no output schema, and half the parameters undocumented, this description is too thin. It never mentions the required idempotency_key, the email recipient cap, or how the schedule relates to the report_id it seeds from, leaving real gaps an agent must resolve by guessing.

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

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

Schema description coverage is only 50% across 10 parameters (including nested body/query objects), so the description is expected to compensate and does not: it says nothing about cadence values, recipient_emails limits, brand_id, report_id, or idempotency_key. The schema itself documents name, next_run_at, workspace_id, and the override objects, but the description adds zero parameter meaning on top of it.

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

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

The description states a specific verb and resource ('Create a new report schedule'), which is unambiguous on its own. It does not, however, distinguish itself from adjacent siblings such as aidelly_create_report, aidelly_update_report_schedule, or aidelly_list_report_schedules, so the agent must infer the boundary from names alone.

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

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

There is no guidance on when to use this versus alternatives, no prerequisites (e.g., that a seed report must already exist), and no exclusions. The only usage-adjacent content is the quota statement, which is a constraint rather than a when-to-use rule.

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=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description usefully adds the 'synchronous' execution trait, which is real behavioral context beyond the annotations, but omits credit cost, failure/partial-output behavior, and the relationship between the required idempotency_key and idempotentHint=false.

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

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

A single front-loaded sentence with no filler; the core action and its pipeline are stated immediately. Nothing is redundant or padded.

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

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

For an 11-parameter tool with nested objects and no output schema, one sentence is not enough. It does not describe what a synchronous job returns, how long it blocks, credit implications, or error semantics for invalid (medium, shape) pairs, leaving the agent under-informed despite the reasonably detailed 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 55%, with medium/shape/sourceRef/sourceText/workspace_id well documented in the schema itself. The description only restates the (medium, shape) pairing and adds the single-target constraint; it says nothing about sourceType variants, the generic body/query overrides, or sourceTitle, so 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?

The description gives a specific verb and resource ('Run a synchronous repurpose job') and outlines the pipeline stages (extract, distill, generate), which is more informative than the bare title. It implicitly distinguishes itself from the read-only siblings aidelly_get_repurpose_job / aidelly_list_repurpose_jobs by describing job creation/execution, though it never names them.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing. The phrase 'for one (medium, shape) target' hints that multiple targets require multiple calls, but this is left to inference, and no prerequisites (e.g. workspace_id required for content creation) are stated.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description carries the interesting burden and does it well: it discloses automatic publishing, pending-approval state under Team Approvals, per-platform rejection of documents with a 422, and retry semantics via idempotency_key. Note the mild tension with idempotentHint=false, though the retry-safety is keyed on an explicit idempotency_key parameter rather than being unconditional, so this reads as nuance rather than contradiction. What is not disclosed is the response shape (e.g., the created scheduled post's id/status).

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

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

Four sentences, front-loaded with the core action, then escalating detail on approvals, platform constraints, and retry safety — a sensible ordering. Some redundancy: the LinkedIn PDF limits and document-title behavior are repeated almost verbatim from the payload schema description, so a sentence partially duplicates structured data.

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

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

For a 12-parameter, nested-object mutation with no output schema, the description covers the highest-risk behavioral facts (auto-publish, approval hold, platform rejection, retry safety) but omits what a caller gets back, whether an unscheduled/draft state is reachable, and the valid platform set. Adequate to avoid the main mistakes, 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 coverage is only 42%, so the description should compensate more than it does. It adds real meaning for two params — recycle ('up to 3 reposts and 3 reshares', refining a maxItems of 6) and idempotency_key (repeat calls return the original result) — but leaves platform (no allowed values), brand_id, timezone default behavior, account_id vs workspace_id, and scheduled_at format/timezone interaction entirely to the bare schema. Partial compensation for a 12-parameter tool.

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

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

States a specific verb+resource with a distinguishing scope qualifier: 'Schedule a post for a future time', which separates it from create_post and create_draft. It also names two distinctive capabilities (auto-recycle entries, approval gating). It never names a sibling tool explicitly, so the agent must infer the create_post vs create_scheduled_post boundary from the word 'schedule' alone.

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

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

Useful conditional context is present: approval gating when Team Approvals is on, and the LinkedIn-only rule for document posts. However, there is no explicit routing guidance such as when to choose this over aidelly_create_post, aidelly_bulk_create_posts, or aidelly_create_draft, and no stated prerequisite (e.g., that workspace_id is required when creating content, which is only in the schema).

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no auth/permission requirements, no uniqueness behavior for target_url, and no reconciliation of the required idempotency_key against idempotentHint=false.

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

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

A single short sentence with no filler, so it is not verbose. But the brevity is under-specification rather than economy — there is no second sentence earning its place by adding required 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?

Seven parameters, two required, a nested body/query escape hatch, and no output schema; an agent needs to know what the response contains (the short URL) and whether reusing an idempotency_key returns the prior link. None of that is provided, so the definition is incomplete for a mutation 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?

Schema description coverage is only 57%, yet the description explains no parameters at all — nothing about target_url length/format constraints, brand_id, source_platform, or the body/query escape hatches. It therefore fails to compensate for the documented coverage 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?

Specific verb ('Create') plus resource ('short link') with a scope qualifier ('on the workspace'), so the agent knows this produces a link object rather than a post or report. However, it does not differentiate itself from the many link-creating siblings (create_connect_link, create_report_link, create_client_review_link), and 'manual' is undefined.

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 when-to-use guidance, no prerequisites, and no mention of alternatives despite several link-creation siblings. 'Manual' vaguely implies an automated counterpart exists, but the description never states the condition that selects this tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, and the description adds nothing on top of them. Notably it never explains that a required idempotency_key is needed for retry safety — a real tension with idempotentHint=false — nor that workspace_id becomes required for this creation call, both of which are material behaviors for a write 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?

One short, front-loaded sentence with no filler or redundancy. It is efficient, but the brevity is partly under-specification rather than disciplined compression.

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

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

For a 13-parameter, nested-object creation tool with an openWorld hint and no output schema, a single sentence is insufficient. An agent is left without guidance on the mandatory idempotency_key, workspace_id requirements, linking constraints, or what a successful creation 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 85%, so the schema already carries most parameter meaning and a baseline of 3 applies. The description contributes at most a weak nod to workspace scoping ('in the workspace') and says nothing about the undocumented idempotency_key, the linked_idea_id/linked_post_id mutual exclusion, or required vs optional fields.

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

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

States a specific verb and resource ('Create a new task') with the workspace scope, which is enough for an agent to know what the tool produces. It does not, however, distinguish itself from the many other create_* siblings or say anything about the task's relation to posts/ideas.

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 offers no when-to-use guidance, no prerequisites, and never names an alternative (e.g., create_post, create_idea, or update_task once the task exists). The agent must infer usage purely from the name.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety burden is partly lifted. The description adds useful context that the subscription covers post lifecycle and inbox events, but says nothing about the signing secret, retry/delivery behavior, or that a required idempotency_key must be supplied even though idempotentHint=false.

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

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

A single front-loaded sentence with no filler; the parenthetical example earns its place. It is arguably too terse for a 9-parameter creation tool, though that shortfall is better counted against completeness.

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

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

For a 9-parameter, nested-object creation tool with no output schema and thin schema coverage, the description is substantially incomplete. It omits the required idempotency_key, the secret used for payload signing, workspace scoping, and default event 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 9 parameters and only 33% schema description coverage, the description needs to compensate and does not. It only loosely gestures at the events parameter ('post lifecycle and inbox events') and leaves url, secret, brand_id, description, and idempotency_key undocumented anywhere.

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

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

States a specific verb+resource ('Create a webhook subscription') and narrows the scope to post lifecycle and inbox events, including a concrete example event (inbox.lead.captured). Sibling differentiation (delete_webhook, list_webhooks, list_webhook_deliveries) follows from the name rather than being spelled out in the description.

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 when-to-use guidance, no prerequisites (e.g. needing a workspace or a reachable endpoint), and no named alternative or condition that would steer the agent elsewhere. The event scope hints at intent but implies rather than states usage.

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

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

Annotations already declare write (readOnlyHint=false), non-destructive, and open-world behavior, so the safety profile is covered. The description contributes genuinely new behavior: the idempotency-key retry contract, which the schema only hints at. Minor tension with idempotentHint=false is resolved by the explicit 'same idempotency_key' qualifier (different keys still create distinct workspaces), so this is added context rather than a 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?

Two sentences, zero filler, and the core action leads the text with the retry guarantee second. Every clause earns its place by adding either scope or behavioral information.

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

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

For a 7-parameter mutation with no output schema and only 43% schema coverage, the description is thin: it omits the meaning of workspace_type and brand_id and says nothing about what a successful creation returns (an id the agent presumably needs for subsequent calls). It is adequate for a simple create but leaves real gaps.

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

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

Schema description coverage is 43%, so the description should compensate but only clarifies idempotency_key semantics, which is the parameter most likely to be misused. Nothing is said about the required 'name' constraint (1-100 chars), the workspace_type enum (traditional vs agentic), brand_id, or the workspace_id note about operating 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?

States a specific verb+resource ('Create a new workspace') and adds ownership scope ('owned by the API key owner'), which tells the agent whose account the resource lands in. It does not explicitly contrast with sibling workspace tools (get/update/delete/list_workspaces), but the verb+resource is unambiguous on its own.

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

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

Implies usage via the retry guidance ('a repeat call with the same idempotency_key returns the original result'), which tells the agent this is the entry point for provisioning and that retries are safe with the key. It never states when to prefer this over alternatives or what preconditions (permissions, plan limits, brand_id context) must hold.

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, but the description adds real context beyond them: the deletion is irreversible, it cascades to a stored file and derived Brain knowledge, it needs workspace settings permission, and it is retry-safe with the same idempotency_key. That is exactly the behavioral detail an agent needs before firing a destructive call.

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

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

Four short sentences, front-loaded with the action and its blast radius, then irreversibility, permission requirement, and retry semantics. No filler and nothing important buried at the end.

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

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

For a destructive, no-output-schema mutation the description covers the essentials: permanence, cascade scope, permission prerequisite, and idempotency. The remaining gap is ambiguity around the `id` (implicitly the document id) and whether workspace_id applies to a delete, given the schema's note that it is optional for reads and required for creates.

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% (id, brand_id and idempotency_key have no schema description), so the description has some compensating work to do. It usefully explains idempotency_key's retry semantics, which the schema's pattern/example alone does not convey, but leaves `id` and `brand_id` uninterpreted and does not clarify whether workspace_id is required for this delete.

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

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

States a specific verb and resource ('Permanently delete a workspace Brain document') and goes further by naming the collateral scope: 'its stored file and the Brain knowledge derived from it'. The word 'Permanently' cleanly separates it from the archive-style sibling aidelly_archive_brain_entry without needing the schema.

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

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

Usage is implied by 'Permanently delete' plus the prerequisite 'Requires workspace settings permission', which tells the agent a permission gate exists. However, it never explicitly routes the agent away from aidelly_archive_brain_entry when archival would suffice, nor states when-not to delete, so it stops at implied guidance.

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

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

Annotations already declare destructiveHint, idempotentHint, and openWorldHint. The description goes beyond them by spelling out what is actually affected (stored event removed vs. backing post cancelled) and by detailing the idempotency_key retry contract, which is genuinely useful context for a destructive operation.

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

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

Four short sentences, front-loaded with the core action, then the behavioral nuance and retry contract. No filler; the only minor redundancy is 'Returns the deletion result,' which is near-tautological.

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

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

For a destructive mutation with no output schema, the annotations cover the safety profile and the description covers the dual deletion semantics and idempotency behavior. The main gap is the undocumented `query` and `brand_id` parameters, but the essentials for correct invocation are present.

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

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

Schema coverage is only 40% across 5 parameters. The description adds meaning for `id` (the event identifier) and `idempotency_key` (retry-safety semantics), but says nothing about brand_id, workspace_id scoping behavior beyond 'selected workspace', or the nested `query` override object.

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

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

States a specific verb and resource ('Delete a calendar event by id') and adds scope ('from the selected workspace'). It also clarifies a non-obvious behavior—deletion may manifest as post cancellation—which helps distinguish it from the many delete_* and cancel_* siblings, though it never names a sibling explicitly.

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

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

Usage is implied by the mention that it 'cancels the post when the calendar uses scheduled posts as its backing store,' which hints at overlap with cancel_post/cancel_scheduled_post. However, it never states when to prefer this tool over those alternatives, nor any 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real substance beyond them: irreversibility and its reversible substitute, 404 behavior for unknown ids AND for links in another workspace, and the retry-safe idempotency_key semantics. This closely matches the annotations rather than contradicting them.

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

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

Four tight sentences, front-loaded with the action and its permanence, followed by error and retry semantics. No filler or restatement of the title.

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

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

No output schema exists, yet the description covers failure modes (404) and the idempotent return, which is what an agent needs. The remaining gap is the unexplained query/brand_id parameters, though these look like generic plumbing.

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%, so the description should carry more of the burden. It clarifies id (via the 404-on-unknown-id statement), idempotency_key retry behavior, and implicitly workspace scoping ('links in another workspace'), but says nothing about the query override object or brand_id. Partial compensation for the coverage 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?

States a specific verb and resource (delete a calendar share link) plus the concrete effect: the public /calendar/share/<token> URL stops working. This distinguishes it from the many sibling delete_* tools (delete_short_link, delete_task, etc.) by naming the exact resource and its user-visible consequence.

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

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

It names a reversible alternative ('disabling the link in the Aidelly app') which gives clear when-to-use/when-not guidance. It stops short of routing to a sibling MCP tool, but for an irreversible delete the alternative framing is the guidance that matters.

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

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

Annotations already flag destructiveHint and idempotentHint, yet the description adds genuinely non-redundant behaviour: the hard-vs-soft delete decision rule, the fact that history grouping is preserved, the soft_deleted response flag, and the dual 404 case for unknown ids and other-workspace campaigns. This is exactly the extra context annotations cannot carry.

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

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

Four sentences, all front-loaded with the core action first, then the delete-mode semantics, then error behaviour. Every sentence contributes; only "Either way the campaign stops appearing anywhere" is mildly restating an implication.

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

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

With no output schema, the description usefully explains the soft_deleted flag and error responses, which is what an agent needs to interpret results. The one real gap is parameter guidance for the five inputs, particularly the required idempotency_key, which is never addressed.

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% across five parameters, and the description adds almost nothing: it never mentions idempotency_key, brand_id, workspace_id, or the query override object. "404 for unknown ids" loosely implies the id parameter but provides no format or constraint guidance, so the description fails to compensate for the coverage 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?

States a specific verb and resource ("Delete a content campaign") and immediately scopes the operation against the rest of the catalogue by naming the campaign object, which is distinct from sibling delete tools like aidelly_delete_draft or aidelly_delete_content_automation. An agent can identify the target entity without opening the schema.

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

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

Gives clear conditions under which it should be relied on: campaigns with no scheduled/published posts are hard-deleted, those with history are soft-deleted, and unknown or cross-workspace ids return 404. It does not name an alternative tool, but no sibling performs campaign deletion, so the omission is minor.

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 and idempotentHint, but the description adds real value: it spells out the concrete consequence of the deletion ('no longer runs on future triggers') and the retry semantics ('a repeat call with the same idempotency_key returns the original result'). It omits permission requirements and error behavior when the id is absent.

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

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

Three short sentences, front-loaded with the action, with no redundant or filler content. Each sentence contributes a distinct fact (action, consequence, idempotency).

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

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

For a destructive mutation with annotations already covering safety and idempotency, and no output schema, the description supplies the key missing behavioral context. Only auth/permission needs and not-found handling remain unaddressed.

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

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

Schema coverage is only 40%, so the description must compensate. It explains the two required parameters well — 'by id' and the idempotency_key retry behavior — but says nothing about the optional brand_id, workspace_id, or query 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?

States a specific verb and resource ('Delete a content automation rule by id'), making the operation unambiguous. It does not explicitly distinguish itself from the sibling delete_inbox_automation, but the resource naming inherently separates them.

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

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

The description implies usage by explaining the effect ('no longer runs on future triggers'), but it never states when to delete versus disabling via update_content_automation, nor names any alternative. Guidance is inferable rather than explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the fact that drafts are unpublished; it says nothing about permanence, recoverability, or what happens when the id doesn't exist, which is the kind of context that would earn credit above the annotation baseline.

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

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

Two short sentences, the action front-loaded before the domain gloss. Nothing is padded, though the second sentence's payoff for an agent selecting a tool is modest.

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

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

No output schema exists, so the description carries the full burden for a destructive, 5-parameter tool. It leaves the required idempotency key, workspace scoping, and failure/recovery behavior undocumented, which is not sufficient for correct invocation.

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

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

Schema coverage is 40%, so the description must compensate, and it only accounts for the 'id' parameter ('by id'). The required 'idempotency_key' is completely unexplained in both the schema and the description — a significant gap for a destructive operation.

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

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

Specific verb+resource ('Delete a draft by id') with a clarifying gloss that the target is unpublished work-in-progress content. It doesn't explicitly distinguish itself from sibling tools like aidelly_delete_post_comment or aidelly_update_draft, but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites, no exclusions. The clause 'work-in-progress content that never publishes' hints that this is destructive but low-exposure, yet it never says when a caller should delete a draft versus update it or leave it in the list.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further by explaining what destruction means concretely (the rule stops firing on future triggers) and by spelling out the retry contract ('a repeat call with the same idempotency_key returns the original result'), which the idempotentHint flag alone does not convey. It stops short of noting permission requirements or behavior when the id does not exist.

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

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

Three short sentences, front-loaded with the action and identifier, then effect, then retry contract. Each sentence earns its place, and the idempotency detail is valuable given there is no output schema.

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

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

For a destructive, 5-parameter tool with no output schema, the description covers the action, the effect of deletion, and the idempotent retry behavior. Remaining gaps are minor: no mention of required scopes/permissions or what happens on an unknown id, and brand_id remains undocumented.

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%: id, brand_id, and idempotency_key have no descriptive text, while workspace_id and query do. The description adds real meaning for idempotency_key (retry-safe semantics) and confirms id is the rule selector, but leaves brand_id and the sparse query override object unexplained, so it only partially compensates for the coverage 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?

States a specific verb and resource ('Delete an inbox automatic reply rule') plus the selector ('by id'), which cleanly separates it from create_inbox_automation, update_inbox_automation, and get_inbox_automations. The second sentence clarifies the effect on behavior ('no longer handles future triggers'), removing any ambiguity about what 'delete' means here.

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 its use case (removing a rule by its id) but never states when to delete versus disabling or updating via aidelly_update_inbox_automation, nor any preconditions. Usage is inferable rather than instructed.

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 useful context beyond annotations: soft delete (recoverable) and an authorization rule (author or workspace owner). Annotations already cover destructive/idempotent hints, so this is additive but limited—no detail on side effects or what a soft-deleted comment looks like.

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 tight sentences, front-loaded with the action and its mutation trait, then the permission constraint. 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?

For a destructive, multi-parameter mutation with sparse schema documentation and no output schema, the description leaves required parameters, idempotency behavior, and the scope of 'soft delete' unexplained.

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 33%; the description never explains required id, commentId, or idempotency_key, nor the optional brand_id/workspace_id/query overrides. With low coverage, the description should compensate 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?

States a specific verb (soft delete) and resource (a comment), and clarifies the soft-delete nature. Distinguishable from siblings like delete_task or update_post_comment, though it doesn't explicitly name them.

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

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

Implies deletion of a comment but gives no explicit when-to-use vs when-not, no mention of alternatives like update_post_comment (for editing instead), and no prerequisites beyond the permission sentence.

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, so the safety profile is covered. The description adds real value beyond that by clarifying this is a SOFT delete that sets active=false rather than removing the record, which refines the meaning of 'destructive' for the agent. It omits permissions, workspace scoping, and what happens to already-queued report runs.

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

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

A single front-loaded clause with the mechanism in parentheses; no filler and nothing to trim.

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

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

For a mutation tool with no output schema, the description covers the core semantics (soft delete, idempotent) but leaves out reversibility, required scoping, and side effects on scheduled runs. Adequate as a minimum viable statement, 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 only 40% across 5 parameters, and the description names none of them. It alludes to idempotency (mapping loosely to the required idempotency_key) but never explains the required id, brand_id, or the opaque query override object, so it fails to compensate for the coverage 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?

States a specific verb and resource ('Soft-delete a report schedule'), which cleanly distinguishes it from the many other delete_* siblings by resource name. The parenthetical adds the exact mechanism. It stops short of explicitly contrasting with siblings like update_report_schedule, but 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?

There is no guidance on when to use this versus alternatives such as aidelly_update_report_schedule (which could also set active=false) or aidelly_list_report_schedules. No prerequisites or exclusions are stated; usage is only implied by the verb.

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

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

Goes well beyond the annotations: it specifies exactly what is destroyed (redirect plus click history), that the action is irreversible, the 404 behavior for unknown ids and cross-workspace ids alike, and the idempotency contract that a repeat call with the same idempotency_key returns the original result. Annotations only carry the flags; the description explains their consequences.

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

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

Four compact sentences, no filler, and the destructive consequence plus irreversibility are front-loaded before the id-sourcing and error behavior. Every sentence carries information an agent needs.

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

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

With no output schema, the description still supplies the effect, irreversibility, id provenance, error semantics (404 for unknown/cross-workspace ids), and idempotency guarantees. The only unstated detail is the exact success payload, which is minor for a delete operation.

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

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

Schema coverage is only 40%, but the description compensates for the two required parameters: it sources `id` from aidelly_list_short_links and explains the retry semantics of `idempotency_key`. The optional `query` and `brand_id` overrides remain unexplained in both schema and description, and `workspace_id` is covered only by the schema.

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

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

States a precise verb+resource (delete a short link) and immediately qualifies the effect: the /l/<slug> redirect stops working and click history is removed. This is unambiguous versus the many other delete_* siblings in the toolset.

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?

Tells the agent where link ids come from (aidelly_list_short_links) and warns that the operation is irreversible, which is real usage context. It stops short of naming an alternative or an explicit when-not (e.g. archive vs delete), so it does not reach a 5.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the delete is soft, the task is hidden rather than removed, and the change is reversible. This tempers the destructive hint in a way the agent could not infer from structured data alone.

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

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

A single front-loaded sentence with zero filler, and the most decision-relevant fact (soft, restorable) comes first. Nothing could be cut without losing information.

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

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

For a 5-parameter mutation tool with no output schema and a required idempotency_key, the description is too thin. It omits the idempotency contract, workspace scoping, and what a caller gets back, which matters for a write operation touching tasks.

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

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

Schema coverage is only 40% across 5 parameters, yet the description explains none of them. It does not mention the required idempotency_key, the workspace_id scoping rule, brand_id, or the odd 'query' override object, leaving the agent to rely on sparse schema text. This fails to compensate for the coverage 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?

States a specific verb and resource ('soft-delete a task') and adds the distinguishing scope ('hidden but can be restored'), so an agent knows this is not a hard purge. It does not name any sibling for differentiation, but the operation itself is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as aidelly_update_task (to modify) or aidelly_get_task/aidelly_list_tasks. The description never states when a soft-delete is preferable to other mutating 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, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that - no statement about irreversibility, what happens to pending deliveries, or required auth/scope.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably undersized for a destructive five-parameter tool.

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

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

For a destructive mutation with five parameters at 40% description coverage, no output schema, and a required idempotency_key whose semantics are unexplained, this description leaves significant gaps. The annotations cover safety but not the operational detail an agent needs to call it correctly.

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

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

Schema coverage is only 40%, and the description contributes just 'by ID', which the schema already conveys via the id property. The required idempotency_key has no explanation of its role (uniqueness, replay behavior), and brand_id is undocumented in both places, so the description fails to compensate for the coverage 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 gives a specific verb (Delete) and resource (webhook subscription) plus the keying parameter (by ID), so the operation is unambiguous. It does not explicitly differentiate itself from siblings like aidelly_create_webhook or aidelly_list_webhooks, though the verb makes the distinction obvious from 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?

There is no guidance on when to use this versus alternatives, no prerequisites, and no note that deletion is permanent or how to find a webhook id (e.g., via aidelly_list_webhooks). The agent gets only the operation name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: 'soft-delete' tells the agent the data is not hard-purged, and it explains the idempotency mechanism (a repeat call with the same key returns the original result) rather than just asserting idempotence. It still omits permission requirements and whether/when a soft-deleted workspace can be restored.

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

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

Three short sentences, no filler, with the operation and its destructive nature front-loaded before the confirm_name guard and the retry guarantee. Every clause carries actionable information.

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

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

For a destructive, 7-parameter mutation with no output schema and thin schema coverage, the description covers the two critical inputs but leaves gaps an agent would care about: what happens to the workspace's dependent content, whether the soft-delete is reversible and by what means, and the role of reason/brand_id. Adequate but not complete for the tool's complexity.

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

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

Schema description coverage is only 29% across 7 parameters, so the description must compensate and does so for the two riskiest: confirm_name (exact-match requirement, absent from the schema) and idempotency_key (retry semantics, beyond the schema's pattern/example). The remaining parameters (reason, brand_id, workspaceId, query) get no explanation in either place, leaving the compensation partial.

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

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

States a specific verb+resource ('Soft-delete a workspace') that cleanly separates it from sibling mutations like aidelly_update_workspace and aidelly_create_workspace. The 'soft' qualifier also hints at the operation's nature, though it does not explicitly name a sibling alternative such as archive.

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

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

It gives a precondition ('confirm_name has to match the workspace name exactly') that tells the agent how to call it successfully, and the retry note implies when re-invocation is safe. It never says when to delete versus when to archive or update instead, nor what state the workspace must be in, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the specific blast radius (credential deleted, syncs stopped, imported products removed), the irreversibility, and the retry-safe idempotency_key semantics. This is exactly the behavioral detail annotations cannot convey.

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

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

Three tightly packed clauses — action/effects, warning, retry semantics — with zero filler and the destructive consequence front-loaded. Every sentence earns its place.

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

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

For a destructive tool with no output schema, the description covers consequences and idempotency well, and annotations cover the safety profile. The remaining gap is that the identity of the required `id` (which store identifier is expected) is not disambiguated against the other id-like 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 coverage is only 40% across 5 params, so the description should compensate more. It explains idempotency_key behavior (repeat call returns original result), which adds real meaning, but leaves the critical `id` ambiguous (store id vs brand/workspace id) and says nothing about 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?

States a specific verb (disconnect) and resource (connected ecommerce store), then enumerates the concrete effects: deletes connection and credential, stops future syncs, removes imported products. Clearly distinguishable from the sibling aidelly_sync_ecommerce_store and aidelly_get/list_ecommerce_stores.

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

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

The description gives strong usage context — irreversible, and the caveat that reconnecting re-imports the catalog — which steers the agent away from using it casually. However, it never names an alternative (e.g., sync vs disconnect, or how to merely pause syncing), so the when-not-to-use path is inferred rather than stated.

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

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

Goes well beyond the annotations: credit cost (12 per coach run), rate limit (5 coach runs/min per API key), fallback behavior (too little data -> rule-based plus coachUnavailable, no charge), and retry safety via idempotency_key. These are the operational facts an agent needs before spending credits that annotations alone don't 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?

Front-loads the core purpose and consequence-bearing constraints (cost, rate limit, retry) in a tight paragraph. It is dense and slightly crammed into one block, but every sentence carries distinct information.

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

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

For an 11-parameter mutation tool with no output schema, the description covers the highest-risk aspects (charges, rate limits, fallback, idempotency) thoroughly. It omits any mention of brand_id and the sparse-schema body/query overrides, leaving a couple of parameters unexplained.

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 (82%), so baseline is 3, but the description adds real meaning: coach's cost and fallback, regenerate semantics, the 90-day date range cap, and the platform fallback when platforms has exactly one entry. It does not explain brand_id or the body/query override objects, so it stops short of 5.

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