Dalea AI

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

With annotations only covering the safety profile, the description adds substantial behavioral context: card is created 'no AI', the suggestion's text is NOT changed, nothing is published, the already-added failure mode, and the return shape. These are exactly the side-effect details an agent needs before invoking a mutating 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 dense but well-ordered paragraph that front-loads the action and effect, then layers the overrides, non-effects, failure mode, and return value. No filler sentences; each clause 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?

No output schema exists, and the description compensates by naming the returned { suggestion, content } pair. It also covers side effects and failure conditions thoroughly, but the unexplained brandId parameter leaves a minor hole in an otherwise complete picture.

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

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

Schema description coverage is 0%, so the description carries the burden and it only partly compensates: scheduledDate is well defined (YYYY-MM-DD or ISO, overrides the suggested date as the planned date) and suggestionId is implied by the failure condition, but brandId is never mentioned or explained.

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 (accepts a brainstorm suggestion) and spells out the concrete effect: creating a content card in the idea column from title/idea/funnel stage, then flagging the suggestion as added with contentId. It reads clearly against siblings like dismiss_brainstorm_suggestion, list_brainstorm_suggestions, and create_content.

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

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

Gives a clear usage context plus a failure precondition ('Fails if the suggestion was already added') and notes scheduledDate overrides the suggested date. It does not explicitly contrast with alternatives such as dismiss_brainstorm_suggestion or create_content, so the routing guidance 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?

Annotations only flag the operation as non-read-only, idempotent and open-world; the description adds substantive behavior beyond them: extraction is asynchronous, its result becomes available to script generation, and duplicate attachment is deduplicated. It does not say how to observe completion or what happens on quota overflow.

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 that front-load what is attached and that extraction starts in the background, then add constraints. 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?

With no output schema and light annotation coverage, the description covers the mutation's safety-relevant behavior well (async, idempotent, quotas, PDF precondition). Minor gaps remain around the identifier parameters and how the caller learns extraction finished.

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

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

Schema coverage is only 33%, and the description documents the source shape (text length, PDF path origin) which the schema already partially covers, but leaves contentId and brandId completely unexplained — no hint on which content card is being modified or how brandId relates to it. It does add the 200–150000 character bound and the create_content_source_upload provenance for pdfPath.

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 ('Attach an article URL, raw text ... or uploaded PDF') plus the consequential side effect ('start AI extraction in the background'). An agent can distinguish this from create_content_source_upload (which only stages a PDF) and get_content_source (which only reads).

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

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

Gives concrete operating conditions: PDF URLs must be downloaded by the agent and uploaded first, reattaching returns the existing ID, and quotas (max 5 sources / 3 PDFs per card). It never names a sibling as the alternative tool, so the routing is implied 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 cover the safety profile (not read-only, not destructive), and the description adds real behavior beyond them: dedupe semantics ('if an active fact with the same text already exists it is returned instead of duplicated (created: false)'), the default category, and an explicit non-effect ('does not regenerate the creator memory'). The only tension is that this dedupe behavior reads as idempotent while the annotations set idempotentHint=false, which is a minor inconsistency rather than a misleading claim.

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 core action, then defaults, then dedupe behavior, then the boundary note. No filler and every clause carries information an agent would otherwise have to guess.

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 3-param mutation with no output schema and no schema descriptions, the description should say more about the return shape (only 'created: false' is disclosed) and about brandId/targeting. Safety and dedupe behavior are covered, so it is adequate but leaves clear 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 0% across 3 params, and the description compensates only partially: it explains what 'fact' is and that 'category' defaults to 'preferencia', but never lists the enum values or says what 'brandId' scopes the fact to. Baseline 3 for a partially-compensated low-coverage schema.

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

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

States a specific verb and resource ('Record a fact about the creator in the learning ledger') plus the implied source (manual) and status (active). The closing line 'Does not regenerate the creator memory' explicitly separates it from update_creator_memory/regenerate_creator_memory, so an agent can distinguish it from the many sibling *creator_fact and *creator_memory tools without opening a schema.

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

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

Usage is only implied: the dedupe rule and the 'does not regenerate the creator memory' note tell the agent this is a single-fact append rather than a memory rebuild, but there is no explicit statement of when to prefer this over add_restriction, review_creator_fact, or update_creator_context, and no 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 the safety profile (not read-only, not destructive, not idempotent). The description adds genuinely useful behavior beyond that: whitespace normalization, a character cap, deduplication of identical restrictions, and the return shape (full restriction list). Minor friction comes from the stated 280-char cap conflicting with the schema's maxLength of 300.

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 clauses, front-loaded with the core definition and no filler. Efficient, though the trailing negation clause is slightly awkwardly attached.

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 with no output schema, the description covers return value, dedup semantics, input normalization, and scope boundaries. The unexplained brandId parameter and the 280/300 cap mismatch are the only 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 description coverage is 0%, so the description must carry parameter meaning. It explains handling of 'text' (normalized, capped) but the stated 280-char limit contradicts the schema's 300, and brandId is not explained at all, leaving half the parameters 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?

States a specific verb (add) and resource (restriction) and immediately defines what a restriction is ('something the brand never wants in its content'), so an agent can distinguish it from list_restrictions, remove_restriction, and the creator-fact tools without opening any schema.

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

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

The negative scoping clause ('Does not touch creator facts or script preferences') usefully routes the agent away from add_creator_fact and update_script_preferences, but there is no explicit when-to-use guidance and no forward reference to list_restrictions/remove_restriction as the complementary 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 only cover the read/write/open-world profile, but the description adds the async contract ('returns pending while the analysis runs'), deduplication behavior ('reuses an active run'), a retry policy with a concrete time window, an authorization prerequisite, and a durable side effect (storing the business analysis). That is meaningful behavioral disclosure well beyond what the structured hints 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?

Compact and front-loaded: the core action comes first, followed by async behavior, retry rules, and non-goals. Nearly every clause carries information, though the trailing API reference URL is boilerplate that adds no selection value.

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

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

No output schema exists, and the description does cover the key return-state concept (pending vs. completed) plus persistence of the result, which is what an agent most needs for an async tool. The remaining gap is brandId's role and whether one is required, which leaves a required-ish decision under-specified.

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

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

Schema description coverage is only 33% – just the 'confirm' parameter is documented, and url/brandId are bare. The description compensates partially by clarifying that url must be a public website and that confirm gates AI usage, but brandId is never explained (is it required? defaults to current brand?). Baseline 3 for a low-coverage schema that is only half-compensated.

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: 'Analyze a public website to understand the brand's business.' It also bounds the operation by naming what it does not do ('does not extract colors or update the strategy brief'), which helps separate it from extract_brand_kit and update_strategy_brief. It stops short of naming its retrieval counterpart get_brand_site_analysis, so sibling differentiation is inferred rather than explicit.

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

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

Gives real operating conditions: the AI usage must be confirmed, an active run is reused, and retry is appropriate after failure or if stuck beyond 10 minutes. The exclusion of color extraction and strategy-brief updates further routes the agent away from adjacent tools. It never explicitly points to get_brand_site_analysis for polling results, which would have made this 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 flag a non-read-only, non-idempotent mutation; the description goes well beyond them by disclosing quota consumption, caching of ready analyses, latency ('waits for completion, may take a few minutes'), and the side effect that the result is saved in the catalog. This is exactly the behavioral context an agent needs before invoking a quota-consuming mutation.

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

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

The purpose and reuse/quota behavior are front-loaded, and the inclusion/exclusion statements are dense but justified. It is a fairly long block with several clauses, though each carries distinct information; no obvious 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 conveys the return payload (analysis + verbatim transcript), the persistence side effect, and the timing/quota model. For a quota-consuming mutation with a 0%-covered schema, this is close to complete.

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

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

Schema coverage is 0% for 4 parameters, so the description must carry the load. It hints at the language override ('brand language unless overridden') and the confirm gate ('requires confirmed AI usage'), but leaves videoId and brandId meaning implicit and does not explain the language enum. 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?

States a specific verb+resource ('Analyze a catalog video'), names the pipeline, and adds the concrete output ('analysis plus verbatim transcript'). It actively distinguishes itself from siblings by declaring what it does not do (no creator's general analysis, no saving as a reference), separating it from analyze_video and save_catalog_video.

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?

Clearly frames the when-to-use conditions: it reuses a ready analysis without consuming quota, but missing/failed analysis requires confirmed AI usage plus a daily quota. The exclusions route the agent away from analyze_video and save_catalog_video. It stops short of naming those siblings explicitly, so routing is 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?

Far exceeds the annotations (which only say readOnly false, idempotent false): it discloses caching behavior, quota consumption (10/day), the confirm gate, what the analysis contains, that manual classifications are respected, that images/carousels are unsupported, that metrics are not synced, and that saved=false means persistence failure. This is exactly the extra behavioral context the annotations don't 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?

Front-loaded with purpose and inputs, then the behavioral caveats. Dense but each sentence carries information (quota, evidence caveat, unsupported media, persistence flag). Slightly list-like but 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 and only safety annotations, the description covers return contents, caching/persistence semantics, quota cost, and media limitations. An agent has everything needed to invoke and interpret a call 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 0%, so the description must compensate. It meaningfully explains platformVideoId (from list_videos), platform (disambiguation), and confirm (required, quota-consuming), covering 3 of 4 params. brandId is left unexplained, which is the only 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 ('Analyze one of the brand's own published video posts') and explicitly scopes it to the brand's own videos, which distinguishes it from analyze_catalog_video. It also names the sibling source tool list_videos, so an agent can identify it without opening a schema.

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

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

Gives clear context: pull platformVideoId from list_videos, pass platform to disambiguate, and confirm=true is required for uncached runs. It implies but never explicitly names the alternative (analyze_catalog_video) or states the condition separating the two, so it stops short of full when/when-not 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 already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely useful clarification: the operation is a soft archive (status change), not a row deletion, and it returns the updated fact. This reframes the destructive hint in a way the annotations alone cannot, though it omits permissions or whether archived facts can be unarchived.

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, zero filler, with the action and its purpose front-loaded before the soft-delete clarification and return value. 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 single-parameter mutation with annotations covering safety and idempotency and no output schema, the description covers the essentials: what happens to the row and what is returned. The only meaningful gap is the undocumented optional brandId and any unarchive path.

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 0% for two parameters. The description explains factId implicitly ('by id'), which is the required parameter, but says nothing about the optional brandId or what scoping it performs, 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?

The description gives a specific verb (archive), resource (creator fact), and scope qualifier ('by id'), plus the effect on downstream generation. It implicitly contrasts with hard deletion by noting the row is kept, though it does not name sibling tools like delete_content or list_creator_facts.

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?

'so it stops feeding generation' implies when a caller would want this (suppressing a fact from generation), and 'The row is kept (status archived), not deleted' hints at the soft-vs-hard-delete choice. However, it never states explicit conditions or names an alternative tool, leaving routing to inference.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive. The description reinforces non-idempotency with a concrete consequence ('calling twice creates the cards twice') and adds facts annotations cannot express: ordering behaviour (created in order at the bottom of their column), no publishing, and the return payload/url semantics.

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

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

Three dense sentences, front-loaded with the core action and limits. Every sentence carries information (scope, item shape, side effects, return value), with only mild redundancy between 'not idempotent' and the annotation.

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

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

With no output schema, the description supplies the return shape { contents, created } and explains the URL, and it covers limits, required fields, ordering, and idempotency. The only gap is the unmentioned optional brandId parameter.

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

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

With 0% schema description coverage, the description compensates well by enumerating the item shape and stating 'title or idea required' plus the optional fields. It omits brandId entirely, which is the one parameter left undocumented in both description and schema.

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

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

States a specific verb and resource with batch scope ('Create 1-20 content cards in one call (no AI)'), which clearly separates it from the singular create_content and the AI-driven creation paths. It does not name those siblings explicitly, so the differentiation relies on the agent inferring from 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 clarifies what does NOT happen ('nothing is published') and the non-idempotent consequence, which is useful context. However, it never says when to prefer this over create_content or create_content_from_source, nor any prerequisites, 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantive behavior the agent cannot get elsewhere: a 10 MiB size cap, the required HTTP PUT method and content type, a 2-hour URL expiry, and the chaining into extract_brand_kit. This is exactly the value-add expected when annotations already cover safety.

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

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

Three sentences, each carrying distinct load-bearing information (what it makes, how to use the URL, how long it lasts) with the core purpose front-loaded. 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 and no nested objects, the description still supplies the return artifact (assetPath), the size/size-limit and expiry constraints, and the downstream step. An agent has everything needed to invoke it correctly and act on the result.

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

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

There is a single brandId parameter with 0% schema description coverage, and the description never explains it, nor does it note that brandId is not required (requiredParameters=0). The intent is inferable from context but not stated. This is the weakest dimension.

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 private signed upload URL for a brand manual PDF.' This cleanly separates it from the sibling upload_brand_logo (logo image vs. manual PDF) and get/update_brand_kit (retrieval vs. URL provisioning). An agent can identify the operation 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 an explicit end-to-end workflow: PUT the PDF bytes with Content-Type application/pdf, then pass assetPath to extract_brand_kit. That names the follow-up tool and the condition for using it. It stops short of stating when NOT to use it (e.g., vs. upload_brand_logo), so it is clear context without 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 cover the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), so the bar is lower. The description still adds real behavior: the default status, the accepted date formats, the required title/idea constraint, the carousel body-separator convention, and what the returned URL is for. It doesn't flag that repeat calls create duplicates, but idempotentHint=false already conveys that.

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

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

Four compact sentences, front-loaded with the core action and the key constraint, with formatting rules for carousel and date placed after. No filler, though the status enum list and API-reference link add mild bulk.

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 mutation tool with no output schema and no schema descriptions, the description explains the essentials (title/idea, status, date, carousel body) and the return URL, but leaves over half the parameters undefined. An agent can call the common path correctly but would guess at platforms, brandId, caption, hook, and cta semantics.

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

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

Schema description coverage is 0% across 13 parameters, so the description carries the burden but only documents title, idea, status, scheduledDate, mediaType/body and partially the return value. The status enum and default are useful, but hook, cta, caption, platforms, brandId, category, and funnelStage have no meaning added anywhere. Partial compensation warrants a 3.

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

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

States a specific verb and resource ('Create a new content card on the board/calendar') and immediately distinguishes itself from the AI-generation siblings like generate_title/generate_hook with '(no AI)'. An agent can differentiate it from create_content_from_source and bulk_create_contents without inspecting 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 clear creation condition ('Requires a title or idea') and implicitly routes agents away from AI-generation tools via '(no AI)'. However, it never names siblings such as bulk_create_contents (for batch) or create_content_from_source (from a source), so the choice among creation tools is left partly to inference.

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

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

Annotations only cover the safety profile (non-read-only, open-world, non-idempotent, non-destructive). The description adds substantive behavior the annotations cannot: default async extraction, the blocking generate=true path and its quota cost, and the partial-failure guarantee that the card ID is preserved for resumption.

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

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

Four tight sentences with the core action and accepted inputs front-loaded, then mode behavior, then the error-recovery guarantee. Nothing is wasted, though the mode/quota sentence is dense enough that it could be split for scanning.

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

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

With no output schema, five parameters at 20% schema coverage, and no annotations on async behavior, the description carries a lot of weight and covers most of it: inputs, source shapes, sync/async modes, quota implications, and failure semantics. The gaps are brandId semantics and any hint of what the call returns on success beyond the card ID.

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 20%, so the description must compensate and largely does: it defines idea as the editorial idea, title as optional and brand-language, enumerates the source variants, and specifies what generate=true does. Only brandId is left undefined in both description and 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?

Opens with a specific verb+resource ('Create a content card') and enumerates the three accepted source shapes (article URL, raw text, uploaded PDF), which lets an agent separate this from create_content and create_content_source_upload 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?

Explains the two operating modes clearly: background extraction by default versus generate=true waiting for extraction and then generating a script against the generate_scripts quota. It does not explicitly name sibling alternatives such as create_content_source_upload, so the routing guidance is implicit 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?

Beyond the annotations (which only mark it non-read-only, non-destructive), the description discloses concrete behavioral traits: the upload is private, signed, capped at 10 MiB, expires after 2 hours, and is consumed via a PUT to the returned uploadUrl. These are exactly the operational constraints an agent needs and are not derivable from the structured fields.

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

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

Two sentences, zero filler, with the verb+resource front-loaded and the size/expiry/workflow details packed into the follow-up. Every clause earns its place.

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

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

For a multi-step upload tool with no output schema, the description does a good job of covering the full flow from preparation through PUT to downstream handoff, effectively describing the returned uploadUrl/pdfPath. It omits any mention that brandId is effectively required and says nothing about failure modes or cleanup of an expired upload.

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 0% for the single brandId parameter, so the description must compensate. 'For this brand' gives only a loose hint that brandId selects the target brand; it adds no format, source, or required-ness detail, leaving the parameter largely 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?

The description states a specific verb and resource ('Prepare a private signed PDF upload for this brand') and immediately situates itself in a workflow by naming the downstream tools (add_content_source, create_content_from_source). An agent can distinguish it from create_brand_kit_upload or upload_brand_logo 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?

It gives clear operational context: PUT bytes to uploadUrl, then pass pdfPath to add_content_source or create_content_from_source. That sequencing is genuinely useful routing guidance, but it never states when this upload path is preferable to alternatives or any preconditions, so it stops short of explicit when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: this is a soft delete and the card disappears from the app, which tells the agent the record is not hard-purged. It stops short of saying whether the deletion is reversible or how to restore.

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

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

Two short sentences with the verb and resource front-loaded, and the soft-delete caveat placed immediately after. 'from the app' is slightly redundant but nothing else is wasted.

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

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

For a two-parameter mutation with rich annotations and no output schema, the description covers the essential behavior including the soft-delete semantics. The unexplained brandId and the absence of failure/permission behavior keep it from being fully 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 0%, so the description must carry the parameter burden. It explains contentId only implicitly ('by id') and says nothing about brandId, leaving half of the two parameters undocumented anywhere. The one hint given does not compensate for the 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 ('Delete a content card') plus the identifying key ('by id'), which is clear enough to distinguish it from sibling mutations like update_content or move_content. It doesn't explicitly contrast itself with the other delete-ish siblings (delete_saved_reference, detach_content_reference), 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 'by id' phrasing and 'from the board/calendar' scope imply the usage context, but there is no statement of when to use this versus unschedule_content, detach_content_reference, or archive-type alternatives, nor any prerequisites. Usage 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: permanence and the explicit negative scope (catalog video and inspirations untouched), which is exactly the information an agent needs before 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?

Two short sentences, zero filler, with the destructive nature and the scope boundary 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 annotations cover the safety profile, so the remaining burden is impact scope — which the description largely discharges. Only brandId's role and any permission requirements are 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 0% across 2 parameters, so the description must compensate. It clarifies savedVideoId's origin (list_saved_references) but says nothing about brandId, leaving half the parameters undocumented in both schema and text.

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 ('Permanently remove a saved reference video') and disambiguates it from nearby delete/detach siblings by declaring what is NOT affected. An agent knows immediately what object is being removed and what survives.

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 tells the agent where the required id comes from ('id from list_saved_references'), which implies a list-then-delete workflow, but it never states when to use this over detach_content_reference or delete_content, nor any preconditions.

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=false, so safety semantics are covered structurally. The description adds useful scoping context about what is and isn't destroyed, but says nothing about permission requirements, reversibility, or the effect on the underlying video/creator/source object. Adequate but not rich, given the annotations carry the safety profile.

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

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

Two short sentences, front-loaded with the action and followed immediately by the scope exclusion. Every clause earns its place with no filler.

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

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

For a destructive mutation with no output schema, the description covers intent and scope but leaves parameters undocumented and omits any auth, reversibility, or post-condition detail. Combined with annotations covering safety hints, it is minimally complete but with clear 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 0% across 3 parameters, so the description carries the full burden, yet it never mentions contentId, referenceId, or brandId. At best 'content card' loosely hints at contentId and 'attachment/video/creator/source' at referenceId, but the mapping and the role of the optional brandId are left to inference.

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 ('Remove') and resource ('an attachment (video, creator or source) from a content card'), and explicitly narrows the scope, distinguishing it from deletion of library references or catalog items. An agent can tell it apart from attach_content_reference and delete_saved_reference 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?

It gives a clear negative boundary ('Does not remove a saved library reference or catalog item'), which steers the agent away from the adjacent delete_* tools. However, it does not positively state when to reach for this tool or name the preferred alternative for library/catalog removal, so it falls short of full when/when-not/alternatives 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 idempotentHint=true and destructiveHint=true, but the description adds real behavioral boundaries the annotations cannot: it does not delete the suggestion, does not touch content cards already created from it, and publishes nothing. It also names the return shape, which matters since there is no output schema.

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

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

Two tight sentences; the primary action and the scope-routing negation are front-loaded 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?

Given no output schema, the 'Returns { suggestion }' note is genuinely useful, and the non-destructive boundaries are complete. However, leaving both parameters undocumented leaves an agent guessing about brandId's role and the identifier format.

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 0% for two parameters (brandId, suggestionId), and the description adds no meaning for either — no format, scoping, or whether brandId is required. With this coverage gap 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+resource ('Mark a brainstorm suggestion as dismissed') and its effect on the pending list. The sibling accept_brainstorm_suggestion and delete_content make the distinction easy to draw from the naming plus the explicit 'does NOT delete' clarification.

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 described effect ('so it leaves the pending list') plus the negations clearly frame when to use this over accept_brainstorm_suggestion or delete_content. It stops short of explicitly naming those alternatives, so the routing is inferable rather than stated.

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

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

Goes well beyond the annotations: it clarifies the original is NOT changed, that references, generations and refine chat are NOT copied, that nothing is published, and that the return includes the new card and a duplicatedFromId along with a url. These are exactly the mutation-boundary facts an agent needs and are not derivable from readOnlyHint=false / destructiveHint=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 tightly packed passage with the action and the scoping constraints front-loaded; every clause (placement, no date, nothing published, return shape) carries information the agent needs. 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 two-parameter mutation with no output schema, the description supplies the behavioral envelope and the return shape (new card, duplicatedFromId, url), which is close to sufficient. It stops short of describing error conditions, required permissions, or what contentId/brandId must refer to.

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 0% and the description adds no meaning for contentId or brandId, nor does it clarify the relationship between them or whether brandId is optional. It lists the fields that get duplicated, which is useful context, but says nothing about the two actual 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 ('Create a copy of a content card') and enumerates the copied fields plus where the copy lands (bottom of the idea column, no planned date). It implies the distinction from create_content by specifying a copy of an existing card, but never names that sibling explicitly to make the routing unambiguous.

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

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

Usage is implied by the detailed statement of what is and is not copied, so an agent can infer this is for cloning an existing card rather than authoring new content. However, there is no explicit when-to-use/when-not guidance and no alternative tool is named, leaving the agent to infer the choice between this and create_content or bulk_create_contents.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavior: the result is non-persistent unless apply is true, PDF extraction may suggest tone styles without touching the strategy brief, and AI usage must be confirmed. That detail materially changes how an agent should sequence the 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?

Five short sentences, front-loaded with the input constraint and the preview-vs-apply distinction. No sentence is filler; each adds a constraint or an effect.

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, non-idempotent, open-world mutation with no output schema and thin schema descriptions, the description covers inputs, authorization, persistence semantics, and a notable side effect. Missing only the role of brandId and any hint of how this pairs with get_brand_kit/update_brand_kit.

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 20%, so the description carries most of the burden and does so for siteUrl/pdfPath (mutually exclusive, one required), apply (persist vs. preview), and confirm (AI authorization). The brandId parameter is never explained in either place, leaving one real 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 (Extract) and resource (visual identity / brand kit) and constrains the input to 'exactly one of siteUrl or pdfPath'. It also separates itself from the analyze_* siblings with 'Does not analyze the business', so an agent can tell it apart without opening other 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 clear preconditions (exactly one source, confirmed AI usage) and explains the default vs. opt-in flow ('returns a suggested kit without applying it; apply true saves it'). It stops short of naming the sibling to use instead when the agent wants to read or modify an existing kit (get_brand_kit / update_brand_kit).

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 substantial detail beyond the annotations: results are options only and nothing is saved or applied (clarifying why readOnlyHint=false but destructiveHint=false), and it consumes a daily quota of 30/day. These are exactly the operational traits an agent needs before calling a metered generation 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?

Three tight sentences, front-loaded with what is produced, followed by the non-persistence caveat, quota cost, and the default. No filler.

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

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

With no output schema, the description correctly states the return shape ('options only') and the cost/limits. It is nearly complete for a 4-param generation tool, with only the brandId/contentId semantics left 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 0%, so the description must carry the load. It does explain the objective default ('engagement') and the count cap (up to 3), but leaves brandId's optionality/fallback and contentId's requiredness unstated, so four parameters remain only partially characterized.

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 ('Generate AI body suggestions for a content card'), plus scope (up to 3) and inputs used (brand context, memory, references). It implicitly separates itself from siblings like generate_hook_options/generate_caption_options by naming 'body', but the boundary with the sibling generate_scripts ('script development') is not fully drawn.

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 (generating body copy for an existing content card), but there is no explicit when-to-use/when-not guidance and no routing to the hook/caption/CTA generator siblings. The quota note hints at caution but not at alternative selection.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false) but the description adds behaviour they do not: the daily quota cost (30/day), the fact that nothing is persisted, and the default objective. Missing only auth/permission notes and any hint about failure modes when quota is exhausted.

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 with zero filler; the primary purpose is front-loaded and the non-persistence and quota caveats follow immediately.

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 appropriately explains that the return is a set of options rather than a saved artifact. It is nearly complete for a low-risk generator, with the only real gap being parameter semantics for brandId/contentId.

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 0%, so the description must carry the parameter burden. It explains the count cap ('up to 3') and the objective default, but says nothing about brandId or contentId semantics (e.g. whether brandId is inferred, whether contentId must belong to the brand), leaving two of four parameters 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?

States a specific verb (generate) plus resource (caption suggestions) and scope (for a content card), which cleanly separates it from the sibling generators generate_body_options, generate_cta_options, generate_hook_options and generate_title.

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 clear usage context by declaring 'Returns options only; nothing is saved or applied', which tells the agent this is a preview step and not a mutation, and notes the quota cost. It does not, however, name alternatives or say explicitly when to prefer this over the other generate_* tools beyond the resource 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 only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false. The description adds real behavioral context beyond that: nothing is saved/applied, and it consumes a daily quota of 30/day, which explains the non-readOnly hint. Return format is not described, but no output schema exists to carry it either.

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 core action and side effects, with zero filler. Every sentence carries a distinct piece of 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 4-param generation tool with no output schema, the description covers what the tool does, that it persists nothing, and its quota cost. It leaves the returned option shape and the optional brandId/contentId relationship unspecified, 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?

Schema description coverage is 0%, so the description must compensate and it only partially does: it clarifies 'count' (max 3) and that 'objective' defaults to engagement, but says nothing about brandId or contentId semantics beyond the implicit 'content card' reference. Baseline 3 for partial compensation.

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 ('Generate'), resource ('call-to-action suggestions'), scope ('up to 3'), and the input basis ('for a content card, using the brand's context, memory and references'). This cleanly separates it from siblings like generate_caption_options, generate_hook_options and generate_body_options.

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

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

Provides clear context ('Returns options only; nothing is saved or applied') which tells the agent this is a non-persisting preview step rather than a content mutation. It does not, however, explicitly route the agent to or away from a named alternative sibling.

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

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

Goes beyond the annotations by disclosing a rate limit ('Consumes daily quota (30/day)'), that nothing is persisted, and a parameter default. This explains why readOnlyHint is false despite 'nothing is saved' (the quota is consumed), which is genuinely useful context. It stops short of explaining auth/permission needs or what the returned option objects contain.

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 core action, then persistence behavior, then quota and default. Every clause carries new information; nothing is restated from the title or schema.

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

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

For a 4-parameter generation tool with no output schema, the description adequately covers what the call produces ('up to 3 options'), that it is non-destructive to content, and that it has a cost. The remaining gap is that an agent still does not know what brandId does or the exact shape/type of the returned options.

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 0% for 4 parameters, so the description must compensate. It clarifies the 'count' ceiling ('up to 3') and supplies the undocumented default for 'objective' ('defaults to engagement'), but 'brandId' and 'contentId' are never explained, leaving half the surface 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?

States a concrete verb and resource ('Generate ... hook (opening line) suggestions for a content card') plus an explicit quantity cap, so the agent immediately knows this is hook copy generation, not body/caption/CTA generation. It does not explicitly name or route against its closest siblings (generate_body_options, generate_caption_options, generate_cta_options), which is what separates a 4 from 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?

'Returns options only; nothing is saved or applied' implies a non-persistent, exploratory call, and 'objective defaults to engagement' hints at configuration. However there is no explicit guidance on when to pick this over the other generate_* option tools, nor any stated prerequisites (e.g., whether a brandId or an existing content card is required).

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 (destructive, non-idempotent, open-world), and the description adds substantial beyond-schema behavior: daily quota of 5 with three AI calls each, no quota consumed when data is insufficient, and saved=false signalling persistence failure. This is exactly the extra context annotations cannot express.

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

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

Extremely dense but front-loaded: eligibility, cost, return shape, and failure semantics are all stated in a few tight sentences with no filler. Every clause 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?

No output schema exists, and the description compensates by naming returned fields (videoCount, sampleSize, generatedAt, saved) and the insights payload. The only gap is that with brandId optional it never says how the target brand is resolved, which matters 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 0% for the single brandId parameter, so the description carries the full burden — yet it never names brandId, states its format, or explains what happens when it is omitted (it is listed as not required). 'The brand's homepage insights' only weakly implies brand scoping.

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: regenerating a brand's homepage insights from top-view video posts, with the input window (365 days, up to 50 posts) stated. It is clearly distinguishable from the sibling get_homepage_insights, which it references as the read counterpart.

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

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

Gives concrete eligibility conditions (needs 10+ videos, images/carousels excluded) and states the quota cost, which tells the agent when the call is worthwhile. It does not explicitly say when NOT to call or route to a preferred alternative, though the get_homepage_insights reference implies read-then-regenerate.

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 substantial behavior beyond the annotations: daily quota consumption (10/day), a 60-second dedupe window that returns the card as-is, bodyOptions/captionOptions saved but not auto-selected, and a returned url for reviewing/editing. This is exactly the side-effect and limit context the structured fields 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?

Dense but front-loaded: the core action and output shape come first, then limits and caveats. Every sentence earns its place, though the mention of non-existent bodyOptions/captionOptions parameters adds slight noise.

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

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

With no output schema, the description still tells the agent what a result contains (url, status skipped) and the quota/save semantics. The dangling reference to bodyOptions/captionOptions not present in the schema is the main completeness gap.

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

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

Schema coverage is 0%, so the description must carry the load. It clarifies durationSeconds ('target spoken length') and the 1-5 contentIds range, but brandId and objective (the enum parameter) go unexplained, and it references bodyOptions/captionOptions parameters that do not appear in the input schema.

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

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

States a specific verb and resource (generate a full AI script) and enumerates the deliverables: hook, CTA, body and caption options, carousel slides. It distinguishes itself from the granular siblings (generate_hook_options, generate_body_options, generate_caption_options, generate_cta_options) by being the full-script generator.

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 useful invocation context (uses brand memory/references/web search when relevant; a card generated in the last 60 seconds is skipped), but never explicitly contrasts with the sibling option generators or states when NOT to use it. Usage is implied rather than routed.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotent. The description adds real context beyond them: that a daily quota of 50 is consumed, that contentId triggers a save, and that it is one short AI call. The save side-effect is disclosed rather than left to the destructiveHint 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?

Two dense sentences, front-loaded with the core action, then the mode distinction, then the quota cost. 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?

No output schema exists, and the description compensates by naming the return shapes ({ content } vs { title }). The only gap is the unexplained brandId parameter.

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

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

Schema coverage is 0%, so the description must carry the burden. It explains contentId (titles and saves existing content) and idea (free-form input), but brandId is never mentioned, leaving one of three parameters 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 (AI-generate) and resource (working title) with two distinct operating modes. An agent can tell it apart from siblings like generate_caption_options or generate_hook_options without opening the schema.

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

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

Explicitly states the selection condition: pass contentId to title existing content, or idea for a free-form idea. Gives clear context for both branches, though it does not name sibling alternatives for other generation tasks.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower, yet the description adds rich context: the exact semantics of followersGained (net followers, gains minus losses, measured from the last snapshot at or before window start), window-echo fields, source-aware freshness fields, and the special handling of accounts without snapshots. It also specifies that includeHealth=true surfaces syncStale and tokenExpired conditions, which are actionable behavioral details beyond the annotations.

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

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

The description is a single dense paragraph with nested parentheticals and long clauses, making it hard to scan. Most content is informative for a tool with no output schema, but the front-loaded verb phrase quickly gives way to a wall of detail, and better formatting would improve readability without losing substance.

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

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

For a read-only tool with three optional parameters, no output schema, and no parameter descriptions in the schema, the description carries the full burden of explaining return values, edge cases (accounts without snapshots), window semantics, and health flags. It covers these completely enough that an agent can understand what it will get and how parameters change the result.

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 0% schema description coverage, the description must compensate. It does so thoroughly for 'days' (range 7-365, default 30, and the snapshot-based measurement semantics) and 'includeHealth' (adds health per account and even to accountsWithoutSnapshots). 'brandId' is only implied by 'the brand's,' leaving one parameter without explicit semantics, so a 4 rather than a 5.

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

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

States a specific verb and resource ('Get the brand's connected accounts') and lists the key returned dimensions (followers, following, followersGained, totalVideos, reach, source, freshness fields). It also distinguishes itself from a day-by-day curve tool with 'Does not return a day-by-day follower curve,' making its scope unambiguous against nearby siblings.

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 detailed description of what is returned (account-level followers and health/freshness), and the negative scope statement hints at an alternative for follower curves. However, there is no explicit when-to-use guidance or named sibling to choose between, so an agent must infer the context.

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

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

Annotations only cover the safe-read profile (readOnly, idempotent, non-destructive), so the description carries real weight beyond them: NET followers semantics, that history begins at connection time, that pre-connection days are null and total.partial flags mid-window connections, that other days are interpolated, that Instagram views only exist ~35 days back, and that scraped accounts may stop updating. This is rich, non-obvious behavioral context.

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

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

Purpose is front-loaded in the first sentence and nearly every clause conveys needed semantics (view source rules, partial flags, best/worstDay gapDays). It is a dense, monolithic block that is hard to scan and could be split, but little of it is wasted for a tool this complex.

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

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

With no output schema and a complex analytics surface, the description fully explains return fields (followers, followersGained, isSnapshot, partial, views, viewsSource, postsPublished, reach, accountsEngaged, and the per-account aggregates) plus the notices field, leaving an agent nothing essential missing to interpret results.

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

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

With 0% schema description coverage, the description must compensate and largely does: it documents days (7-365, default 30, ending today), from/to precedence and the 365-day span limit, and granularity (day default up to 90 days, week ending on `to`). brandId is never explained and platform is only implied by later mentions of Instagram/TikTok.

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 opening sentence gives a specific verb+resource and scope: follower growth and views per day/week for the brand's connected accounts, per account and in total. It is clear what the tool returns, but it never distinguishes itself from similarly-scoped siblings like get_metrics_daily, get_account_overview, or get_performance_summary.

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

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

Usage is only implied through the window/granularity mechanics; there is no explicit 'use this when...' or 'instead of X'. An agent can infer intent from the detailed parameter prose, but no alternatives or exclusions are named.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond them: the tool returns kit: null when no kit was generated yet, which tells the agent how to handle the empty state.

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 with the core resource front-loaded and the null-handling note appended where it belongs. No filler, though it is short enough that slightly more routing detail would have fit.

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

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

For a simple read-only getter with no output schema, the description does reasonable duty describing return contents and the null case. It is missing parameter sourcing and differentiation from the closely named brand-kit siblings, but the core call is unambiguous.

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

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

There is one parameter (brandId) with 0% schema description coverage, so the description carries the burden, yet it never mentions brandId or where its value comes from. It only implies a brand context, which is minimal 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?

Names a specific verb and resource (brand's visual identity kit) and enumerates its contents (colors, fonts, logo, palette, voice description). It implicitly contrasts with update_brand_kit and get_brand_profile, but never names a sibling explicitly to disambiguate from extract_brand_kit or create_brand_kit_upload.

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, when-not-to-use, or alternative routing is given. The clause 'used by the video editor and carousels' describes downstream consumption of the kit, not the condition under which an agent should call this tool rather than extract_brand_kit or get_brand_profile.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine behavioral context on top: it decodes 'cancelAtPeriodEnd true means the subscription ends at currentPeriodEnd instead of renewing' and explains brandSlots, which 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?

The piece is front-loaded with the purpose in the first clause, then a dense parenthetical field list. It is long, but with no output schema the enumerated return fields each carry information an agent needs, so the length largely 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 single-parameter read tool with no output schema, the description does the heavy lifting on return contents (including two fields whose semantics are non-obvious). The one gap is the undocumented brandId parameter, which is the only thing an agent needs to actually invoke it.

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

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

There is one parameter, brandId, at 0% schema description coverage, and the description never addresses it — no format, no mention of which brand is resolved, and no note that it is optional (0 required). The field-name enumeration describes returns, not the parameter, so the schema gap is not compensated.

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 ('Get a brand's full profile') and goes further by enumerating the returned sections (basics, strategy brief, social accounts, subscription). An agent knows exactly what this retrieves. It stops short of explicitly differentiating from close siblings like get_brand_kit or get_account_overview, so it is clear but not fully disambiguated.

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 closing line ('Provides the brand context relevant to content generation and review') gives an implied usage context, but there is no explicit when-to-use vs. when-not guidance and no sibling alternative named. Adequate but leaves the agent to infer selection between this and get_brand_kit/get_account_overview.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine context beyond them: empty days are returned, cards without postedAt are omitted, UTC formatting, the default range, and the reassurance that it 'does not modify scheduled dates'.

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

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

One tight paragraph, front-loaded with the return shape, then the placement rule, then the parameter formats. Dense but every sentence carries information; the 'same rule as the calendars in the Dalea app' clause is the only mildly expendable phrase.

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 enumerates the returned fields (id, title, status, platforms, mediaType, postedAt), so return semantics are covered. The main remaining gap is the undocumented brandId parameter, which is minor for an otherwise complete read-only tool.

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

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

Schema description coverage is 0%, so the description carries the burden and does explain 'from'/'to' as YYYY-MM-DD in UTC with a stated default. However, the third parameter 'brandId' is never mentioned, leaving one of three parameters 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?

States a specific verb and resource ('Get the brand's content calendar') plus the exact output shape: one entry per day, empty days included, with named card fields. It also distinguishes itself from the sibling 'list_contents' by explaining which cards are excluded, so an agent can tell the two apart without opening a schema.

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

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

Gives the default date window (today through next 7 days) and the rule that cards sit on their postedAt day, then routes the agent to 'list_contents' for cards with no postedAt. Clear context and a named alternative, though it never states an explicit 'use this when X' selection criterion.

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

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

Annotations already establish the safe/idempotent read profile, so the bar is lower. The description adds genuinely useful context beyond them: it returns a URL for viewing/editing in the Dalea Carousel Studio and explicitly states no image files are returned, which heads off a likely agent expectation.

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 that front-load the core action and payload, then add the return-format caveat. Nothing is wasteful, though the parenthetical payload list is slightly 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?

With no output schema, the description meaningfully covers the return shape (slides, funnelStage, URL, no images). The main remaining gap is parameter meaning, which drags completeness down for what is otherwise a well-covered read 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 0%, so the description carries the full burden for draftId (required) and brandId (optional). It says nothing about what either parameter means or how brandId scopes the lookup, leaving both undocumented in both schema and 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 ('Get one carousel draft') and enumerates the payload (slides, funnelStage values). The singular 'one' implicitly contrasts with the sibling list_carousel_drafts, but the description never names that sibling, so the differentiation is left to inference.

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: retrieving a single draft by draftId. No explicit when-to-use statement, no prerequisites, and no mention of when to prefer list_carousel_drafts versus this tool. Adequate but with clear gaps.

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it details the exact return payload, the carousel body convention (slides joined by '\n\n---\n\n'), what is deliberately excluded, and what the returned url does. That is rich behavioral context an agent cannot derive from the annotations 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 paragraph that leads with the core action and then groups returns by category; every clause carries information. It is on the dense/long side, but there is no filler to cut.

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

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

With no output schema, the description carries the full burden of describing returns and does so thoroughly, including the carousel edge case and the reference/generation counts. An agent can call this confidently based on the description alone.

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 0% and the description never explains either parameter. 'by id' weakly implies contentId, but the optional brandId is completely undocumented – no format, no reason it is optional when contentId is required, no scoping effect. With zero schema descriptions the description had to compensate and 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 and resource ('Get one content card's full detail by id') and then enumerates exactly which sections come back (script, planning fields, webSearch, counts). This clearly separates it from list_contents (single-card vs collection) and from the reference/generation history tools, which it explicitly excludes.

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 id' and the note that it omits full reference, generation and refinement-history records loosely point the agent at list_content_references/list_content_generations, but no sibling is named and there is no explicit when-to-use or when-not-to-use statement. The 'opens the card in Dalea for review and editing' line hints at a review workflow but doesn't formalize it.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=false, destructive=false, so the safety profile is fully covered. The description adds genuine value beyond that with its explicit negative scope ('Never includes the interview transcript') and a field-level preview. It still omits behavior for the missing-interview case, so a 3 is fair.

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, purpose front-loaded, with the exclusion appended where it belongs. No filler or restated 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?

With no output schema, the description takes on the burden of describing return values and does so by listing the field set. For a read-only single-parameter getter this is largely complete; only the parameter meaning and when-to-use versus siblings are missing.

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

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

Schema coverage is 0% and the single parameter brandId is completely undocumented in both schema and description. Baseline for one optional parameter with no schema docs would be low; the description compensates only by implying a per-creator lookup. It does not explain brandId's role or whether it is required, so this is a clear 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 (get creator context) and enumerates the exact contents returned: phase, origin story, 90-day goals, working content, struggles, themes, voice. This is far more than a tautology. However, it does not distinguish itself from close siblings such as get_creator, get_creator_analysis, or get_strategy_interview, so the agent lacks a routing signal.

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 or when-not-to-use guidance, and no sibling is named as an alternative. The only boundary given is that the transcript is excluded, which is a scope fact rather than usage direction. An agent cannot tell from the text when this tool is preferred over the many other 'get_creator*' readers.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered externally. The description adds one genuinely useful behavioral detail beyond that: a successful read may return null fields when no memory exists yet, which prevents misinterpretation as an error. That is modest added context, not rich disclosure.

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

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

Two tight sentences: the what comes first, the null-state caveat second. No filler, no repetition of 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 read-only getter with full annotations, the description adequately conveys the return shape and the null edge case, and no output schema exists to cover it instead. However, it leaves the only input parameter entirely unexplained, which is a real completeness gap for invocation.

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

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

Schema description coverage is 0% and the single parameter brandId is undocumented in both schema and description. The description never mentions brandId at all, nor that it is optional (required parameters = 0), so an agent could wrongly assume it must supply one. No 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?

Specific verb+resource: retrieves the AI-maintained creator memory and states its shape (free text plus structured fields). It is distinguishable from write siblings like update_creator_memory and regenerate_creator_memory, but it never contrasts itself with the nearby read siblings get_creator_context or list_creator_facts, so sibling differentiation is only implicit.

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

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

There is no statement of when to call this rather than get_creator, get_creator_context, or list_creator_facts. The only conditional content is a data-state note ('fields are null when no memory was generated yet'), which tells the agent how to interpret a result, not when to choose 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/idempotentHint, but the description adds substantial beyond-schema behavior: it never regenerates, the scope rules (50 top-view posts, last 365 days, minimum 10, images/carousels excluded), the exact freshness triggers (language, format, count change of >=5), and a caveat that diagnoses are AI hypotheses not measured retention.

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

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

Front-loaded with the core read verb and returned fields, and the scope/freshness specifics are ordered sensibly. It is dense but mostly earns its place, with a minor redundancy between 'Read-only: never regenerates' and 'Does not regenerate insights.'

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

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

With no output schema, the description carries the full burden and does so well: it documents return fields, the freshness state machine (missing/insufficient_data/stale/available plus reasons and canGenerate), scope limits, and interpretation caveats. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 0% and the single optional brandId parameter is never mentioned in the description. The text richly explains the data scope, which partially compensates, but adds no meaning for the one parameter the agent must supply.

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 ('Read') on a specific resource ('saved homepage insights') and enumerates the fields it surfaces (generatedAt, currentVideoCount, scope, freshness). The 'never regenerates' clause implicitly separates it from generate_insights, letting an agent tell the two apart without opening a schema.

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

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

It establishes clear context for when this applies – reading already-saved insights rather than producing them – and the 'never regenerates' framing points away from the generative sibling. However, it never names an alternative (e.g. generate_insights) or states an explicit exclusion, so routing is inferred rather than prescribed.

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 readOnly/idempotent/non-destructive, and the description adds substantial data-semantics context beyond them: cumulative running totals rather than per-day deltas, one row per account per sync day, the 180-day range cap, and the exact metric fields returned. This is the behavior an agent most needs to avoid misinterpreting the numbers.

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

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

Front-loaded with the core definition, then the row shape and metric list, then the caveats. Most sentences earn their place, though the cumulative-vs-daily warning is stated twice ('NOT activity that happened on that day' and 'not daily views or follower growth'), which is mild redundancy.

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

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

With no output schema, the description usefully enumerates the returned columns (date, platform, cumulative totals, averageEngagementPct), which is exactly what is needed without a formal return spec. Gaps remain on `brandId`, row volume/pagination limits, and explicit alternative-tool routing, but these are minor against the otherwise rich data semantics.

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

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

Schema description coverage is 0%, so the description carries the burden and mostly succeeds: it explains `from`/`to` format, inclusivity, and the 180-day cap, and labels `platform` as an optional filter. It does not explain `brandId` at all, leaving 1 of 4 parameters undocumented in both schema and 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+resource (per-sync daily metric snapshots of the brand's video posts) and precisely scopes what the data is: cumulative running totals, one row per account per sync day. It even distinguishes itself semantically from adjacent concepts (not daily activity, not follower growth), letting an agent tell it apart from siblings like get_audience_growth or get_performance_summary.

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

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

Clear about context: it defines the accepted date format and a hard cap (last 180 days before `to`), and explicitly rules out misreads ('NOT activity that happened on that day', 'not daily views or follower growth'). However, it never names an alternative tool to use for daily-view or follower-growth questions, so routing against actual siblings is left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: the 90-day lookback window for brand videos and the explicit null return when the brand has no videos, which an agent could not infer elsewhere.

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 tightly packed sentences with zero filler; the default output is front-loaded and the conditional compare behavior follows. Every clause 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?

With no output schema and no parameter descriptions, the description does well by naming the compare return fields and the null case, but it does not spell out the shape of the default (non-compare) benchmark response or what brandId defaults to when omitted.

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 0%, so the description must carry the burden. It fully explains `compare` including the field list of the returned `brand` object, but `brandId` is never mentioned, leaving one of two parameters 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?

States a specific verb (Get) and resource (niche benchmarks) and enumerates the exact statistics returned (median/p75/p90 views and engagement). This clearly separates it from performance-oriented siblings like get_metrics_daily or get_top_performers.

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 compare=true behavior is described, giving implicit guidance on when the extra brand-relative output is produced. However, there is no explicit statement of when to prefer this tool over alternatives such as get_performance_summary or get_top_performers, and no prerequisites are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior beyond that: metrics are cumulative totals of posts published in each window rather than activity during it, deltaPct is null when the previous value is 0, and periods use inclusive from/exclusive to timestamps. These are non-obvious semantics an agent could not derive from annotations.

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

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

A single dense paragraph that front-loads the core return fields and then layers the caveats. Every sentence carries information, though the run-on enumeration of return fields is slightly heavy; the front-loading keeps it usable.

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

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

With no output schema, the description correctly carries the full return-shape burden and does so, enumerating metrics, deltas, and topVideo plus the cumulative-totals caveat. What is missing is the brandId parameter's meaning and any mention of which system it reads from, but the core contract is 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 0%, so the description must compensate. It does explain the days parameter (allowed values 7|30|90 and a default of 30 that the schema does not state), but brandId is never mentioned, leaving half the parameters undocumented beyond their names.

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

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

The description clearly states it returns aggregate totals (videoCount, views, likes, etc.) for videos published in the last N days, including previous-window comparison and topVideo. That is a specific resource+operation, and the 'Only video posts are included' line scopes it. It does not explicitly differentiate from sibling analytics tools like get_metrics_daily or get_top_performers, 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?

Usage is implied by the windowing language and the default-30 note, but there is no explicit statement of when to choose this over get_account_overview, get_metrics_daily, or get_top_performers. The agent must infer the routing from the sibling names alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the returned payload contents and the default/max window for `last`, which helps the agent anticipate scope and volume.

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, both front-loaded: the payload description leads, the usage note follows. 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?

With no output schema and no parameter descriptions, the description usefully explains the return payload and the `last` semantics. It is slightly incomplete in leaving `brandId` (and its relationship to contentId) undocumented, which matters for a 3-param 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 0%, so the description must carry parameter meaning. It does well for `last` (default 20, max 100) — notably more precise than the schema's own bounds — and implies `contentId` via 'attached to a content card', but `brandId` is entirely unexplained in both schema and 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 (Get) and resource (refine chat messages attached to a content card), and enumerates what comes back: text, refinement IDs, preview status, proposed changes, settings, and total message count. This is clearly distinguishable from siblings like refine_content (which mutates) and review_content_refinement.

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

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

Explicitly says to use it to 'resume a conversation or review a saved preview', which gives a concrete usage context. It stops short of naming the alternative sibling (e.g., review_content_refinement) or stating exclusions, 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the payload contents (pillars, formats, duration, hooks, instructions), which usefully stands in for the absent output schema, but it discloses nothing about defaults, auth, or behavior when preferences are unset.

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 that enumerates return fields with zero filler. Every clause earns its place.

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

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

For a simple annotated read tool with no output schema, enumerating the returned fields is genuinely helpful and largely compensates for the missing output schema. However, the undocumented brandId and the total absence of usage context leave the definition only minimally complete.

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

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

The single parameter brandId has 0% schema description coverage, and the description does not compensate — it only obliquely implies 'the brand's' via the possessive. It never explains what brandId is, its format, or what happens when it is omitted (the schema marks no required 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?

Specific verb ('Get') plus resource ('the brand's script preferences') and an explicit enumeration of what the resource contains. It reads unambiguously against its counterpart update_script_preferences, though it never names or contrasts with that sibling directly.

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

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

No guidance on when to call this versus alternatives. With generate_scripts, generate_hook_options, and update_script_preferences in the sibling set, the description should say something like 'fetch before generating scripts' or 'read counterpart of update_script_preferences', but it offers nothing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds genuinely useful context beyond that: it returns only the stored interview for this brand and performs no restart/side effect, which tells the agent the call is safe to repeat without mutating state.

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 with the payload front-loaded. The final sentence partially restates the first but earns its place by adding the no-restart and brand-scoping constraints.

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

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

With no output schema, the description compensates by enumerating the returned fields (messages, profile, phase, applied), and annotations carry the safety profile. An agent has enough to call this correctly without opening 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 0%, so the description must compensate. It explains includeHistory directly ('true includes previous archived sessions'), and brandId is made self-evident by 'for this brand'. One of two weak-typed params is fully clarified; brandId's meaning is implied rather than explicit.

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 ('Read') and resource ('strategy interview') and enumerates the payload (messages, profile, phase, applied). This distinguishes it from the mutating sibling 'strategy_interview' via 'without restarting it', though the sibling is not named explicitly.

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

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

The phrase 'without restarting it' and the includeHistory note imply when to reach for this rather than a starting tool, but no alternative is named and there are no explicit when/when-not conditions. Usage 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered externally. The description adds useful operational defaults (days=30, limit=10) but says nothing about return shape or pagination, which is acceptable given the annotation coverage.

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

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

Extremely dense and front-loaded: the core action and scope lead, followed by metric, direction, and limit defaults in telegraphic fragments. Every clause carries information, though the fragmentary style is slightly clipped.

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

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

For a read-only ranking tool with no output schema and annotations covering the safety profile, the description supplies the key knobs and defaults an agent needs to invoke it correctly. Only brandId scope is left implicit, which is minor for a self-evident identifier parameter.

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

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

With schema description coverage at 0%, the description compensates well by supplying defaults absent from the schema (days=30, limit=10, direction=top) and the max for limit. It does not explain brandId or why days is capped at 365, but most parameters are given meaning beyond the raw types and enums.

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 (Rank) and a clearly scoped resource: the brand's videos published in the last N days, ordered by a named metric. An agent can tell what it produces without opening the schema, though it does not explicitly distinguish itself from close siblings like get_performance_summary or get_recommended_videos.

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 mechanic (rank videos by metric over a time window) but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that this is the tool for leaderboard-style ranking versus aggregate metrics.

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

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

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, yet the description adds substantial context beyond them: the full returned payload, analysisStatus state enumeration, legacy unknown language/evidence, null handling for images/carousels, the 5-video minimum for baseline comparison, and the explicit boundary that it does not generate missing analysis.

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

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

Front-loaded with the core action and identifier before the dense return-shape detail. The middle sentences are information-heavy but each adds value given the absence of an output schema, though the run-on phrasing is denser than necessary.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: it enumerates the key fields, statuses, comparison semantics (ratios vs engagementRatePct), and edge cases. An agent has enough to call it and interpret results 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 0%, so the description must carry param meaning. It clarifies platformVideoId as the identifying key and platform as an optional disambiguator, but brandId is never mentioned, leaving one of three parameters 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?

States a specific verb and resource ("Get an own post by platformVideoId") and scopes it to the caller's own content, which helps distinguish it from catalog/search siblings. It does not explicitly name a differentiating sibling like get_content or get_catalog_video, so an agent must infer the boundary from "own post" and the platformVideoId key.

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

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

The phrase "own post" and "Read-only; does not generate missing analysis" imply when this tool applies and hint that analysis generation is a separate concern. However, no alternative is named (e.g., analyze_video for generating analysis, get_content for other content types), leaving routing to inference.

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

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

Annotations already establish the safe read-only, idempotent, non-destructive profile, so the bar is lower; the description adds real value by disclosing the project lifecycle states (queued|processing|preview_ready|ready|expired|failed), the expiresAt/expiringSoon signals, and the important caveat that a finished job whose project is expired has no downloadable video. It does not describe rate limits or auth requirements.

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

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

A single dense but front-loaded sentence that leads with the primary output (job status) before secondary details. Slightly overloaded with parenthetical enumerations, but no wasted framing.

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

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

With no output schema, the description does carry the return-value burden well, listing the fields and expiry caveat, so an agent knows what it gets back. However, it is silent on the two input parameters, leaving a gap for a tool that requires projectId.

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 0% and there are two parameters, yet the description only gestures at the project via prose and never explains projectId's format/role or what brandId is for. It does not compensate for the completely undocumented schema.

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

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

States a specific verb and resource: retrieving the latest render job of a video editor project, and enumerates what comes back (status, stage, progress, error code, project state, URL). It is clearly distinguishable from list_video_projects or get_video, though it never names an alternative to contrast against.

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 guidance on when to call this versus siblings like list_video_projects or get_video, and no stated prerequisites. Usage is only implied by the phrase 'Get the latest render job'.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: the profile is AI-derived and each component is null until generated. It says nothing about permissions, latency, or freshness/regeneration of the profile.

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

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

Two tight sentences with no filler, and the payload contents are front-loaded. The stacked parenthetical lists are slightly dense but still readable.

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

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

With no output schema, the description does the right thing by enumerating the return shape and null semantics. It still leaves gaps: brandId's optionality, and how this differs from sibling get_brand_profile.

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?

One parameter (brandId) with 0% schema description coverage and zero description text about it — the schema marks it as not required, yet the description implies a required brand context without clarifying default behavior or format. With low coverage the description should compensate and 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?

Specific verb (Get) plus resource (the brand's voice profile and form profile), and it enumerates the sub-fields returned (status, confidence, profile, exemplars / stats). However, it never distinguishes itself from the very similar sibling get_brand_profile, so an agent must guess which profile endpoint to pick.

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 a crowded sibling set (get_brand_profile, get_brand_kit, get_creator_context). The null-when-not-generated note is a data caveat, not a usage 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 idempotentHint=true and destructiveHint=true, so the description's restatement of idempotency is redundant. However, it adds real value by clarifying what 'destructive' does NOT mean here - saved references from that creator survive - which prevents an agent from over-estimating the blast radius. No permissions or auth requirements are described.

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 core action and its scope front-loaded before the caveats. Every sentence adds a distinct 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 two-parameter mutation with no output schema, the description covers effect scope, idempotency, and a key non-effect. The main omission is how brandId is supplied or defaulted, which an agent must infer.

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 0%, so the description carries the full burden. It documents the creatorHandle format ('with or without @'), which the schema does not, but says nothing about brandId beyond the vague phrase 'this brand's'. It compensates for one of two parameters, leaving a documented 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 (hide) and resource (creator) scoped to 'this brand's reference catalog searches', which distinguishes it from sibling catalog tools like list_catalog_creators and search_creators. The implicit pairing with unhide_creator is clear from the verb 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?

Explains the operative context (affects catalog searches only) and the idempotent case ('already-hidden creators are left as is'), plus an explicit exclusion ('does not delete saved references'). It stops short of naming unhide_creator as the inverse operation, so the when-not guidance is only partial.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by explaining what each status means and that contentId points to the created content, but it says nothing about pagination, ordering, or result size.

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; the enum semantics are packed efficiently into a parenthetical. No wasted words, though the second sentence is a fragment-style list.

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

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

For a simple two-parameter read with no output schema and annotations covering the safety profile, this is close to adequate. It still leaves the brandId parameter unaddressed and gives no sense of return shape beyond 'reasons' and the contentId pointer.

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 0%, so the description must compensate. It does explain the semantics of the status enum values (pending/added/dismissed and the contentId pointer), but the brandId parameter is left entirely unexplained in both schema and 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 ('List') and resource ('brainstorm suggestions') with scope ('active', 'with reasons'). It does not explicitly distinguish itself from siblings like regenerate_brainstorm or accept_brainstorm_suggestion, but the resource is distinctive enough that an agent can place it.

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 optional status filter is described, which implies how to narrow the listing, but there is no explicit when-to-use guidance or reference to the sibling tools (accept/dismiss/regenerate) that operate on the same suggestions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds what each record contains and how ids are consumed downstream, which is useful but not deep behavioral context.

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

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

Two short sentences, front-loaded with what is listed and followed by the cross-tool id linkage. 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 must convey the return shape, and it names the key fields (niche, connected platforms, active flag). Pagination or ordering behavior is not mentioned, but for a short user-scoped list that is a minor omission.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes slightly further by explaining that returned ids feed the brandId parameter in other tools, tying this list to the rest of the API surface.

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 (List) and resource (the user's brands) and enriches it with the returned fields: niche, connected platforms, and active status. It does not explicitly distinguish itself from the similarly named get_brand_profile sibling, 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 plural framing implies 'use this to enumerate all brands,' but there is no explicit when-to-use or when-to-prefer-get_brand_profile guidance. Usage is inferable rather than stated.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine value beyond them by describing the returned shape (title, slide count, last edit), disclosing that slide texts are omitted, and confirming each draft carries a viewing/editing URL. It says nothing about pagination behavior or permission requirements, which limits it to a 4.

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

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

Three short sentences, front-loaded with the core action and followed by the scope caveat and the return hint. Every sentence contributes something, though the final URL sentence is somewhat detail-heavy relative to the rest.

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

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

With no output schema, the description does a reasonable job sketching the return payload and its exclusions, and annotations cover the mutation profile. The significant gap is parameter documentation: pagination and brand scoping are invisible, which an agent needs in order to call this list tool correctly.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full documentation burden and largely fails it. It never mentions limit, offset, or brandId — pagination semantics and the brand scoping are only faintly implied by 'the brand's'. This leaves two of three parameters entirely 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?

The description names a specific verb and resource ('List the brand's carousel drafts from the Carousel Studio') and enumerates the returned fields (title, slide count, last edit), so its purpose is unambiguous. It does not, however, differentiate itself from the very similar sibling list_carousel_posts or get_carousel_draft, which is the only thing keeping it out of the top band.

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

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

Usage is only implied: the note that drafts exclude 'full slide texts' hints that get_carousel_draft is needed for the full content, and 'the brand's' implies a brand scope. No alternative tool is named explicitly and there are no stated preconditions or exclusions, so the agent must infer the routing itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context by naming what each returned job contains (status, scheduled time, per-platform permalink or error), which matters for a read tool with no output schema, though it says nothing about scoping, pagination, or history depth.

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 enumerating the resource and its payload, followed by a short fragment for the filter. No waste, but the trailing fragment is clipped enough that its role is ambiguous.

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 sketches the return shape, which is its main contribution. However, for a three-parameter listing tool with 0% schema coverage, it omits meaning for two parameters and says nothing about pagination or ordering, leaving 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 0% for all three parameters. The description accounts for 'status' only, and even then without accepted values; 'limit' (bounded 1-100) and 'brandId' (the scoping key) get no explanation anywhere. With zero schema documentation, the description needed to carry this load and 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 and resource ('List carousel/video publish jobs sent to Instagram or TikTok') plus the returned fields, which squarely separates it from sibling list tools like list_carousel_drafts (drafts) and get_video_job_status (single job). An agent can pick this tool without opening any schema.

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

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

The only usage note is 'Optional status filter,' which describes a parameter, not when to choose this tool over list_carousel_drafts, list_content_generations, or get_video_job_status. No prerequisites, no when-not condition, no 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 already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description adds useful behaviour beyond that: results are ordered newest first and each entry contains the title/hook/cta plus alternative body/caption variants. It does not disclose pagination or what happens when no generations exist, so it stops short of a 5.

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

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

Two tight sentences, front-loaded with the scope and return fields before the usage hint. No filler or restated 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?

There is no output schema, so spelling out the returned fields and sort order is exactly the right compensation, and the usage hint covers the workflow. The remaining gap is the undocumented limit/brandId parameters and no statement about result volume or pagination.

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 0% across three parameters, yet the description only implies contentId through 'saved for a content card' and says nothing about brandId or the limit parameter's role, default, or cap. With the schema carrying no prose, 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 (List) and resource (AI script generations saved for a content card), and enumerates the fields returned (title, hook, cta, alternative body/caption options). This is clearly distinct from list_contents and from the generate_* siblings that create the data.

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 gives the use case: 'see what was already tried before regenerating.' That ties the tool to the regeneration workflow, giving a clear when-to-use context, but it never names an alternative tool or states when NOT to use it (e.g. vs get_content or list_contents).

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: postedAt is the planned calendar day and null means unscheduled, limit defaults to 50 with a max of 100, and full scripts are excluded from results.

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

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

Front-loaded with the return shape, then filters, then pagination – a logical order with no filler sentences. The first sentence is dense, but every clause 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?

No output schema exists, so the description's enumeration of returned fields is essential and it delivers, plus filter values, date formats, pagination bounds, and the unscheduled-null semantics. An agent has everything needed to call and interpret this tool.

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

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

With 0% schema description coverage and 9 params, the description carries the load and mostly succeeds: it supplies status values (idea|draft|edited|posted), platform, mediaType, from/to date formats, search matching rules, and pagination defaults/max. Only brandId goes unmentioned, which is a minor 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 (list the brand's content cards) and immediately scopes what is returned: summaries of board + calendar cards with an enumerated field list. It also carves out what it is not ('Does not include the full script'), which separates it from get_content.

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 through the field/filter enumeration and the 'does not include the full script' note, which hints that get_content is the fuller alternative, but the sibling is never named and there is no explicit when/when-not guidance against list_carousel_posts, get_calendar, or list_video_projects.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: the default status of 'active' (a filtering behavior the agent would otherwise miss) and the offset/nextOffset pagination model.

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?

Effectively three front-loaded sentences: what it returns, then filtering behavior, then pagination limits. Dense and largely waste-free, though the parenthetical category list is long and the last clause is slightly compressed.

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 helpfully names return fields (sourceRef, confirmed) and documents the pagination contract. For a six-parameter read-only list tool this is close to sufficient; only brandId and the relative positioning against sibling fact/restriction tools are missing.

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

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

Schema description coverage is 0%, so the description must carry the burden; it explains contentId, status default, limit cap, and pagination, and its category list implicitly decodes the category enum values. It leaves brandId completely unexplained and gives no syntax hints for filtering, so compensation is partial rather than complete.

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

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

Specific verb (list) plus resource (facts learned about the creator), with an explicit enumeration of the fact categories that maps to the category enum. It does not, however, distinguish itself from close siblings like list_restrictions or get_creator_memory, so an agent must infer the boundary.

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 useful invocation context — status defaults to active, limit max 100, and contentId filters facts learned from that content — which tells the agent how to scope a call. It never says when to prefer this tool over list_restrictions, get_creator_memory, or get_creator_context, so usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that results are 'AI-generated insight tiles' (a hint at result content), with no disclosure of volume, ordering, or freshness. Baseline 3 is appropriate given annotation coverage.

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 efficient sentence with the resource front-loaded; nothing is padded or buried. It is held back only by conveying so little in that one sentence.

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

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

With no output schema and one simple parameter, the annotations carry most of the burden, but the description omits sibling differentiation and any detail on what an 'insight tile' contains or how many are returned. Adequate but with clear gaps for an agent choosing among many list_/get_* siblings.

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 0% for the single brandId parameter, and the description only implies brand scoping via the possessive 'the brand's'. It does not state whether brandId is required (the schema marks zero required params) or what happens when it is omitted, leaving the key ambiguity unresolved.

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 (List) and resource (brand's AI-generated insight tiles), which is clearer than the name alone. However, it does not distinguish this from siblings like generate_insights, get_homepage_insights, or list_contents, so an agent cannot route between them from 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?

The description gives no indication of when to use this tool versus generate_insights or get_homepage_insights, nor any prerequisites. There are no exclusions or named alternatives; the agent must infer usage entirely from the name.

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