eonik-mcp

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

No annotations, so description carries full burden. It mentions idempotence, server-side execution, and that results are retrieved via get_ad_deconstruction. However, it does not explicitly state side effects (e.g., creating a stored breakdown) or potential failure modes, but the idempotency hint covers reuse. Slightly more detail on what 'deconstruct' entails would improve transparency.

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?

Description is compact but includes all key information: purpose, idempotence, and usage context. The 'busywork' phrasing is slightly informal but adds no fluff. Sentences are purposeful and front-loaded with the main action.

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

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

Given a single parameter, no output schema, and no annotations, the description covers essential usage: what it does, when to use it, and how to retrieve results. It also clarifies the boundary with sibling tools. Minor gaps: no mention of potential errors or rate limits, but these are not critical for this simple command.

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 covers asset_id with 100% description, and the tool description adds context about asset types (watched competitor, ad-library, TikTok, swipe-file) but this largely duplicates the schema's own description. No additional syntax or format guidance is provided, so it hovers at the baseline.

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

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

Description clearly states the verb (deconstruct) and resource (public ads: competitor, ad-library, TikTok, swipe-file) and specifies the server-side actions (scene-split, transcribe, structural analysis). It also distinguishes from sibling tools like get_ad_deconstruction (for reading) and get_shot_deconstruction (for own footage).

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 when to use ('when the marketer says break this down') and provides a clear exclusion: 'For the marketer's OWN footage, use get_shot_analysis.' It also instructs to read results via get_ad_deconstruction, giving a complete usage flow.

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

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

With no annotations provided, the description carries the full burden. It does add useful behavioral context: generation is done by a 'server model,' the output is 'receipt-bound,' and it makes no performance predictions. However, it does not disclose side effects such as persistence, costs, permissions, reversibility, or rate limits, leaving significant ambiguity for a tool with no annotation 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?

The description is compact and efficient, packing deprecation guidance, purpose, output shape, a prerequisite, and a limitation into a single, well-structured sentence. There is no filler or repetition of schema details.

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

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

For a simple one-parameter tool with no output schema and no annotations, the description is largely complete: it provides the scope, the output shape, the critical deprecation warning, and a key limitation. It loses one point because jargon like 'receipt-bound' is unexplained and the side-effect profile remains ambiguous, but overall it gives enough context for an agent to decide against using it.

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

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

The schema already documents 'slate_item_id' with 100% coverage, so the baseline is 3. The description adds value by specifying the parameter must reference an 'approved slate item,' a meaningful eligibility constraint not present in the schema. It does not add formatting or syntax detail, but for a single-parameter tool this is adequate.

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 what the tool does: 'Compose eonik's grounded creative brief for an approved slate item via a server model' and enumerates the exact output structure. It also differentiates itself from the sibling 'get_brief_grounding' by explicitly deprecating itself in favor of that alternative.

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

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

The deprecation notice 'prefer get_brief_grounding + author it yourself' provides explicit guidance on when not to use this tool and names the preferred alternative. The 'approved slate item' constraint and the limitation 'No performance predictions' further clarify the tool's scope of use.

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

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

With no annotations, the description bears full responsibility. It states 'Facts, never a verdict,' indicating the tool returns objective data rather than interpretations, but it does not mention potential issues like rate limits, errors, or data availability, leaving some behavioral aspects undisclosed.

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

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

The description is compact, using two sentences to convey the tool's purpose, content, and usage guidance. It is well-structured and free of fluff.

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

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

It includes the output fields and a practical usage note. However, it does not elaborate on the meaning of 'active_ads_recent' or potential edge cases (e.g., missing data), but overall it leaves the agent with enough context to use the tool effectively.

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

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

The tool has no parameters, so the description does not need to explain them. Since the schema is empty, the description's mention of output fields is sufficient and adds no unnecessary param-related content.

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

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

The description clearly states that the tool retrieves the brand's current operating condition, listing the exact fields (state, last_active, days_since_active, active_ads_recent) and the possible states. It differentiates from sibling tools by focusing on account condition/recency rather than ad performance or competitor 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?

It explicitly advises to 'check this before advising' and explains why a dark account requires a different first message than a live one, giving clear situational guidance for when to use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It extensively explains nuances: non-comparability of rates across auctions, null behavior, the meaning of held/faded, the direction of delta, and the fact that winners+losers equals judged_ads not tested_ads. No contradictions exist.

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

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

The description is lengthy but each sentence serves a purpose—clarifying interpretation, warning about pitfalls, and defining key terms. It is front-loaded with the primary purpose and structured around major concepts. While it could be trimmed, the density of critical caveats justifies the length.

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

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

Given zero parameters, no annotations, and no output schema, the description is exceptionally complete. It explains the shape of the output, field semantics, null handling, temporal horizons, and interpretation guidelines, ensuring an agent can correctly use the tool without external references.

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

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

The tool has zero parameters, so the baseline is 4. The description adds depth by explaining the meaning of output fields and how to interpret them, which is essential given the lack of an output schema. It does not need to describe parameters since none exist.

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

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

The description clearly identifies the tool as retrieving the user's own ad account testing history, with specific outputs (scopes, by_dimension allocation, winners/losers) and unique comparative logic against auction medians. It distinguishes from sibling tools like get_account_condition or lookup_ad_performance by focusing on account memory and receipt-like details.

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

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

The description implicitly clarifies usage: it's for the user's own account, not competitors or external data, and explains the two horizons (craft_profile vs craft_standing) answer different questions. It does not explicitly state when NOT to use it or name alternatives, but the context is strong enough that an agent can infer appropriate usage scenarios.

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

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

With no annotations, the description carries the full burden. It states 'Facts only' (read-only) and explains that data is 'stored once per unique creative and reused' indicating no side effects. It does not specify error behavior when the asset_id is not found, but it does direct to deconstruct_ad for that case, leaving some ambiguity.

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 detailed but each sentence contributes useful information: content, methodology, storage, purpose, and fallback instruction. It is slightly verbose but not excessively so, and the structure flows logically from what to why to how.

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

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

Given the complexity (no output schema), the description adequately explains the return payload (transcript, genome, scene details) and the tool's purpose. It references the companion tool deconstruct_ad for creation, providing enough context for a user to understand when and why to call this getter.

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 sole parameter asset_id is well-described in both the schema and the description, listing the valid ad sources. Since schema coverage is 100%, the baseline is 3; the description adds value by clarifying the 'public ad' context and the types of assets, so a 4 is warranted.

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

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

The description clearly states that the tool retrieves a precomputed scene-by-scene breakdown of a public ad, listing the exact content (transcript, genome, scenes with attributes). It distinguishes itself from sibling tools like deconstruct_ad by explicitly noting it fetches existing data and instructing to call deconstruct_ad if none exists.

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 provides a clear usage context: use to reason about creative STRUCTURE, and explicitly says to call deconstruct_ad first if no deconstruction exists. However, it does not contrast with other retrieval tools like search_competitor_ads or get_my_competitor_ads, so the guidance is not fully comprehensive.

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

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

With no annotations, the description carries the burden of explaining behavior. It discloses that the tool returns durable media for cloning and specifically notes when it returns clonable=false with a reason (only a still archived). It does not explicitly state read-only behavior, but as a 'get' operation it is implied, and the description is sufficiently clear about its outcomes.

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

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

The description is concise (two sentences) and well-structured, presenting the purpose, usage context, and an important edge case without unnecessary fluff. Every sentence adds value.

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

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

The description covers the main purpose, usage context, and a notable edge case. It implies the normal return (the ad with durable media) by stating what it retrieves. Since there is no output schema, the description is reasonably complete, though it does not explicitly enumerate the success return structure; however, for a simple get tool, this is adequate.

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

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

The schema provides a description for the single parameter asset_id, listing possible ID types (watch_asset / ad-library / tiktok / swipe id). The description does not add further meaning beyond that, but since schema coverage is 100% and the type is clear, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves an archived public ad by ID for cloning, with specific mention of durable media (video, poster, permalink, copy). It distinguishes from search tools by emphasizing 'resolution by id, never a scan of a cached page' and provides usage context for when a deep link or slate item points to an asset not in the local corpus.

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

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

Explicit usage guidance is provided: 'Use when a deep link or a slate item names an asset the local corpus does not hold' and clarifies the approach (by ID, not cached scan). It also describes the edge-case behavior when only a still is archived, which helps the agent know when to expect a failure or fallback.

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

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

With no annotations, the description carries the full burden. It discloses the tool's non-destructive nature by stating it's auto-loaded at session start, and it specifies that corpus inventory contains counts, not contents, setting expectations. It doesn't mention permissions or side effects, but for a zero-parameter read operation, this is sufficient.

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, long sentence but packs in all essential facts without redundancy. It front-loads the core purpose ('Orientation for THIS brand') and lists specific content elements. It's structured and readable despite its length, earning a high score.

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

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

For a zero-parameter tool with no output schema, the description is remarkably complete. It details what the tool returns (identity, rails, verbatim quotes, competitive changes, corpus counts) and even clarifies the counts-vs-contents distinction. Combined with clear usage timing, this fully equips the agent to decide when to 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and it doesn't attempt to add redundant information. It focuses on the tool's purpose and output, which is appropriate.

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

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

The description clearly states the tool's purpose: providing brand orientation including identity, guidelines, verbatim marketer notes, competitive changes, and an inventory of available corpora. It uses a specific verb ('get') and resource ('brand briefing') and distinguishes itself from sibling tools like get_brand_context by focusing on session-start orientation and corpus availability.

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

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

Explicit usage guidance is given: the editor auto-loads at session start, and the agent should call it to refresh mid-session, after switching brands, or when needing to know what is available before choosing a tool. This clearly indicates when to use it and implies it's a precursor to tool selection, though it doesn't explicitly name alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It says the tool returns the full brand DNA but does not mention whether data is cached, how recent it is, any access constraints, or that the operation is strictly read-only. The lack of such details is a gap for a tool that agents might rely on for strategic decisions.

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

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

The description is a single sentence, well-structured, and front-loaded with the tool's purpose and a list of contents. Every word contributes meaning, with no redundancy or fluff.

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

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

For a zero-parameter getter with no output schema, the description provides a clear list of what is returned and a usage context. It is sufficiently complete for typical use, though it could mention limitations (e.g., data freshness or scope) to fully cover edge cases. Overall, it meets the needs of an agent selecting 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 zero parameters, the baseline is 4. The description adds value by enumerating the content categories returned, which is helpful context even though there are no input parameters to explain. The schema is empty and fully covered (100%), so no additional parameter documentation is needed.

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

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

The description clearly identifies the tool as retrieving the user's complete brand DNA, listing specific elements (name, category, audience, etc.). This is a specific resource-level verb ('get') with clear scope, distinguishing it from sibling tools that target competitors, ads, or playbooks.

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 provides a usage context ('Use for any strategic brand question') but lacks explicit when-not-to-use guidance or mention of alternatives. While the broad scope is implied, it doesn't compare against other knowledge tools like get_context_ledger or get_brand_briefing, leaving room for ambiguity.

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?

No annotations are provided, so the description carries the burden. It makes the behavioral contract clear enough: the tool returns factual grounding 'as DATA', the agent must do the reasoning, every reference must be 'traceable to a receipt', and no performance predictions are allowed. It does not explicitly say 'read-only', but 'Get... as DATA' strongly implies retrieval without mutation.

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

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

The description is dense, but it front-loads the core purpose and then adds useful workflow constraints. The parentheticals and capitalized terms make it a bit run-on, but nearly every clause carries functional information rather than filler.

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

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

Given a single-parameter input and no output schema, the description provides enough context: it explains what the grounding contains, who writes the final brief, and what guardrails apply. It does not fully spell out the exact raw return shape of the tool, but the schema and described workflow are sufficient for an agent to invoke it correctly.

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

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

The schema has one required parameter, slate_item_id, and the schema description already fully covers it: 'The slate item id to brief.' The description reinforces the usage context by referencing 'write the brief for #2', but it adds no new parameter-level semantics. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's verb and resource: "Get the receipt-bound GROUNDING for a slate item's brief" and enumerates exactly what data is returned. It also distinguishes itself from sibling tools by saying 'Prefer this over generate_creative_brief — you author, not a server model.'

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 tool gives explicit trigger phrases: 'Use when the marketer says "write the brief for #2" / "turn that into a brief"'. It also provides an explicit alternative comparison, naming generate_creative_brief and explaining why this tool should be preferred.

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

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

The description transparently indicates that the tool returns factual data and not predictions, and details the output (hook_type x creative_style performance). However, it does not explicitly state read-only behavior or lack of side effects, though it is implied by the nature of a 'get' operation.

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

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

Two dense sentences convey all essential information without redundancy or extraneous details.

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

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

Given the simple nature of the tool and single parameter, the description sufficiently covers what data is returned and how to invoke it. No output schema is provided, but the description enumerates the key output dimensions.

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 'identifier' is fully described, including that partial name matching is allowed and that it refers to Meta campaign IDs. The description adds depth beyond the schema by clarifying the matching behavior.

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?

Clearly specifies the tool retrieves performance metrics (spend, CTR, creative breakdown) for the user's own campaigns, distinguishing it from competitor-related sibling tools by emphasizing 'OWN campaigns'.

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 how to reference campaigns (partial name or exact ID) and what kind of data it returns, providing clear context for when to use it. The phrase 'Facts only, no predictions' further clarifies its appropriate use.

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

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

With no annotations, the description carries the transparency burden. It implies a read-only operation through the verb 'get' and the phrase 'Facts only,' but it does not explicitly state side effects, permissions, or that no modifications occur. A more explicit statement would improve transparency.

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 redundant and somewhat tangled. Phrases like 'The category conversation pulled by hashtag' and 'every watched TOPIC ... with its captured Instagram post count' repeat similar information, and the pointer to another tool could be integrated more cleanly. A more streamlined structure would improve clarity.

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?

Without an output schema, the description gives a basic idea of the return content (topics and Instagram post counts) and notes 'Facts only' to imply data reliability. It lacks details on the exact structure or fields, but is sufficient for a basic understanding.

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 sole parameter 'brand_id' is fully described in the schema, including its default behavior. The description adds no extra detail beyond the schema, so it meets the baseline but does not enhance understanding.

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

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

The description clearly states that the tool retrieves category topics (hashtag bundles) along with their Instagram post counts, and distinguishes topics from competitors. The verb 'get' and resource 'category topics' are explicit, though the phrasing is somewhat verbose.

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

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

The description provides a pointer to a related tool (get_competitor_assets) for loading a topic's posts, which gives some context on when to use this tool vs. that one. However, it does not explicitly enumerate scenarios or compare with other sibling tools, leaving usage guidance 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?

With no annotations provided, the description carries the full burden. It discloses ordering (newest-published first), pagination (page by page), summary contents (totals, run lengths, video mix, coverage), and that each ad includes a watch_asset_id for deconstruction. It also warns about include_summary being channel-scoped and a performance consideration when paging.

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 brief, front-loaded, and every sentence adds value: purpose, key field, usage context, and channel slug list. No fluff or redundant restatements.

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

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

There is no output schema, so the description explains the summary fields and the watch_asset_id. It does not enumerate all ad fields, but given the schema covers parameters and the description covers output highlights, it is sufficiently complete for an agent to predict the tool's behavior. Minor gaps include not describing error cases or what happens if no ads exist.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by listing the canonical channel slugs (meta_ad_library, tiktok_ad_library, etc.) which are not enums in the schema, and by explaining the purpose of watch_asset_id and the include_summary behavior beyond the schema 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?

The description states exactly what the tool does: retrieves one competitor's captured ads for one channel, page by page, newest first, with a whole-set summary. It explicitly differentiates from siblings by emphasizing 'ONE competitor' and 'ONE channel', and names the prerequisite get_competitor_channels.

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

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

The description gives a clear 'Use after get_competitor_channels' instruction and implies the tool is for a single competitor/channel. However, it omits the alternative source for competitor_id (topic id from get_category_topics) mentioned in the schema, so the guidance is not exhaustive.

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

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

No annotations are provided, but the description discloses that it returns counts, coverage, and read states, and explicitly warns it provides facts only, not scores. This is good behavioral context, though it doesn't mention pagination, performance implications, or whether the data might be cached/stale. Given the lack of annotations, a 3 is appropriate.

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

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

The description is a single, dense paragraph that front-loads the core value proposition (

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

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

The tool is relatively simple (single optional param, no output schema), so the description is adequate: it covers the data returned, the use cases, and distinguishes read state. It could mention that it's a read-only operation, but given the lack of destructive implications and the strong factual framing, it's complete enough.

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

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

Schema coverage is 100% (brand_id is described), but the description adds context:

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

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

The description clearly states the tool lists every competitor under watch with per-channel captured-ad counts and coverage, and explicitly names the channels (Meta Ads, TikTok, Google/YouTube, Instagram). It also clarifies the output is facts only, distinguishing it from analysis tools like get_competitor_patterns or get_competitor_timeline.

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

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

It explicitly states when to use: 'Use to show the Competitors rail and channel tabs, or to answer

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?

No annotations are provided, so the description carries the burden. It discloses that it returns counts only (no predictions) and requires at least one deconstructed ad. However, it doesn't mention whether this is a read-only operation, potential rate limits, or what happens if no deconstructed ads exist (error vs. empty result).

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

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

Two sentences, front-loaded with the core purpose, includes concrete examples, and ends with a clear prerequisite. Zero waste.

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

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

For a single-parameter tool with 100% schema coverage and no output schema, the description is quite complete. It explains what the tool does, what it returns (counts, not predictions), and the prerequisite. The only gap is edge-case behavior (no deconstructed ads), but that's minor given the prerequisite is stated.

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

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

Schema coverage is 100% (competitor_id is described as 'The BrandCompetitor id (from the brands the user watches)'). The description adds context that the competitor must have deconstructed ads, but doesn't add much beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool aggregates structural patterns across all of a competitor's deconstructed ads, with specific examples (problem-solution hook, editing rhythm, first-scene shot). It distinguishes from siblings by emphasizing 'aggregated patterns' vs. individual ad retrieval (get_ad_deconstruction, search_competitor_ads).

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

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

The description implies when to use: when you need aggregated structural patterns across a competitor's ads, not individual ads. It notes the prerequisite of at least one deconstructed ad. However, it doesn't explicitly contrast with alternatives like get_competitor_timeline or get_craft_playbook, though the 'counts only, no predictions' clarifies scope.

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

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

With no annotations, the description carries the behavioral burden. It discloses ordering (newest first), includes lifespans, archived media, and emphasizes the observed_* vs platform_* field separation, which is a key behavioral trait. It also clarifies 'Facts only, no predictions.' It does not mention error handling or authentication, but for a read-like tool this is acceptable.

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

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

The description is dense but each clause adds unique value: ordering, lifespans, archived media, observed/platform distinction, asset_id linking, and facts-only guarantee. It is structured with clear periods and front-loaded with the core purpose. No redundancy; each sentence earns its place.

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

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

Given no output schema, the description adequately explains the return: chronological roster, lifespans, archived media, observed/platform fields, and asset_id for further lookup. It also mentions the continuous-monitoring nature. This covers the essential context an agent needs to interpret the output and decide next actions.

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

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

Schema coverage is 100% with clear descriptions for all four parameters (limit, channel, active_only, competitor_id). The description does not add meaningful parameter-level details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves the chronological roster of one competitor's archived creatives, with specifics like newest-first ordering, lifespans, and archived media. It distinguishes from sibling tools like search_competitor_ads by focusing on a single competitor, and from get_my_competitor_ads by implying external brand tracking.

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

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

The description implies when to use: for a single competitor's complete archived history that cannot be reconstructed from other sources (continuous-monitoring archive). It also sets boundaries with 'Facts only, no predictions' and hints at using deconstruct_ad for deeper investigation. However, it does not explicitly name alternative tools for contrasting scenarios, so a slight deduction applies.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the source authority (what the marketer told eonik), the types of content (truths, plans, corrections), currency signals (dated, recent), and its role as an overriding source. It stops short of describing exact output formatting or update mechanics, but for a zero-parameter read tool this is strong 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?

The description is compact and front-loaded with purpose, then uses brief illustrative examples and a prioritized usage directive. Every sentence adds value, with no redundant fluff or repetition of the tool name.

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

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

For a parameterless retrieval tool with no output schema, the description sufficiently covers what the ledger contains, why it matters, and when to use it. It could be even more complete by explaining how it relates to sibling context tools like get_brand_context or get_account_memory, but it remains highly actionable on its own.

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 has zero parameters, so there are no parameter semantics to clarify. The baseline of 4 applies, and the description compensates by clearly defining the scope of what will be returned.

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 identifies the resource (a proprietary marketer-supplied ledger) and its contents: durable brand truths, dated plans, and recent corrections. It also distinguishes this tool from generic alternatives by stating it is the proprietary input no competitor or general agent can scrape and that it overrides generic best practice.

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 explicit usage guidance: 'ALWAYS read this before giving strategic advice' and notes that it overrides generic best practice. It does not name sibling alternatives or formal when-not-to-use cases, but the unconditional 'ALWAYS' provides clear context for when this tool should be selected.

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

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

With no annotations present, the description carries full burden. It discloses that this is 'descriptive only' and not causal, that counts come from ads that survived and sometimes from shorter-running ones, and that it may return `unavailable` with a reason. It also specifies the nature of the data (counts over what survived), which is transparent about limitations.

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 relatively long but information-dense. Each sentence adds value: the opening defines the output, the middle lists specifics, and the end gives usage guidance and caveats. It is front-loaded with the core purpose, though it could be tightened without losing content.

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

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

For a tool with one parameter, no annotations, and no output schema, this description is remarkably complete. It explains the full return content, the context of use, the caveat about causality, and the unavailable case. The agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with the single parameter `competitor_id` already documented as 'The competitor id from get_competitor_channels.' The description adds no additional parameter-level detail, but the baseline of 3 applies because the schema is fully self-sufficient. No extra compensation needed.

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

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

The description clearly states the tool's purpose: showing how a competitor's surviving ads are made, with specific craft pointers (hook, opening lines, shot length, etc.). It uses specific verbs like 'returns' and 'carries,' and the scope ('competitor's surviving ads') differentiates it from sibling tools like search_competitor_ads or get_competitor_patterns.

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

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

Explicit usage guidance is provided: 'Use when asked "what works for <competitor>", "how do they make their ads", or when briefing an editor.' It also states when it returns `unavailable` and that it should be described plainly. However, it doesn't name alternatives or explicitly state when not to use it, so it misses the top score.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. It discloses that the tool returns only facts (creative, hook, days-running) and explicitly excludes scores or predictions, which is valuable beyond the tool name. It does not mention auth, rate limits, or failure modes, but for a simple read-only list tool this is reasonably transparent.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, then adds a clarifying scope and a practical use-case quote. Every part earns its place with no redundancy or filler.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately conveys what the tool returns (ads with creative, hook, days-running facts) and what it excludes. It could be slightly more complete by mentioning ordering or pagination, but the core usage is well covered.

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

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

Schema description coverage is 100% for the single 'limit' parameter, which already includes its meaning and default value. The description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves ads from the user's configured competitors, with a specific scope: 'facts only (creative, hook, days-running), no scores or predictions.' This distinguishes it from sibling tools like search_competitor_ads and get_competitor_patterns by emphasizing both the data source and the factual-only nature.

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

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

The description explicitly provides a use case: 'Use for "what are my competitors running?"' This gives clear context for when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios.

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?

No annotations are provided, so the description must disclose behavioral aspects. It merely states 'get' without mentioning side effects, permissions, data usage, or any rate limits. There is no mention of read-only behavior or potential impact, making it insufficiently transparent for a tool with no annotation support.

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

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

The description is highly concise, consisting of two short sentences. It efficiently states the purpose and usage without any redundant information, making it easy to parse and understand.

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 getter with one parameter and no output schema, the description covers the core functionality and provides a usage hint. It lacks details on return format or any edge cases, but these are not required given the simplicity. Overall, it is sufficiently complete for its purpose.

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

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

The schema fully describes the only parameter 'limit' with its default and max. The tool description does not add any extra meaning to this parameter beyond what's in the schema, so it meets the baseline for high schema coverage (100%).

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?

Clearly states it retrieves the user's recent Monday slates and consideration items, with specifics like concept, why-now, receipts, reactions. The verb 'get' and resource 'slates' are specific, but it does not explicitly differentiate from sibling tools that might also fetch slates, such as competitive analysis tools.

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

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

Provides explicit usage guidance: 'Use for questions about their slates.' This indicates when to invoke the tool. However, it lacks exclusionary guidance (e.g., when not to use) and does not compare with alternatives, leaving some ambiguity in the broader toolset.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is 'descriptive, receipt-backed, never predictions' and 'Degrades honestly per scope', which sets expectations about output nature. It also explains the medium omission behavior and the offer_text semantics, which are behavioral traits. However, it doesn't detail what happens on missing data or error conditions, but the key behavioral aspects are covered.

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, but it's packed with information. It front-loads the core purpose and then lists the key attributes. It's not overly long given the complexity of the tool. However, it could be slightly more structured with bullet points, but the prose is efficient and every sentence adds value.

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

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

Given the tool's complexity (9 parameters, no output schema, no annotations), the description does a good job of explaining what the tool returns (pattern facts, survivor rates, temporal class, etc.) and how to use it. It doesn't explain the return format, but since there's no output schema, that's a gap. However, the description is quite complete for the agent to understand when and how to invoke it. It could mention what happens if the draft signature is missing, but overall it's solid.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds value by explaining the overall conditioning ('Pass the draft's signature') and clarifying the medium parameter's default behavior and the offer_text's three-state semantics. It also explains the purpose of draft_text ('enables 'analyzed ads like this draft''). This goes beyond the schema's individual descriptions, so it earns a 4.

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

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

The description clearly states the tool's purpose: it provides time-aware NormsPack for pre-export reality check, scoped and windowed pattern facts with specific attributes. It distinguishes itself from siblings by emphasizing 'pre-export reality check' and 'draft_comparisons', which is unique among the listed tools. The verb 'get' plus the resource 'validation_grounding' is specific and the description elaborates on what the pack contains.

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

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

The description explicitly says 'Pass the draft's signature so the pack is conditioned on THIS draft' and explains the medium parameter's effect ('Omitting this treats the draft as motion...'). It also clarifies the offer_text parameter semantics ('Send an EMPTY string to mean... omit the field entirely to mean...'). This provides clear when-to-use and how-to-use guidance, though it doesn't explicitly name alternatives, the context is clear enough.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It describes the returned content types and receipts and implies a read-only aggregation, but it does not state side effects, prerequisites such as an existing watchlist, refresh behavior, or what 'receipts' means.

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 one front-loaded sentence that immediately states what the tool returns, followed by a compact usage cue. There is no filler, repetition of schema, or annotation information.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description adequately covers the output categories and intended question. It is slightly incomplete because 'receipts' is undefined and watchlist behavior is not explained, but it remains sufficient for a simple retrieval 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?

The only parameter, 'days', is fully described in the schema with default and maximum values; the description adds no additional parameter semantics. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description specifies a distinct resource ('competitors the user is watching') and concrete output categories ('new ads, proven winners (30+ days), organic outliers') plus 'receipts'. This clearly distinguishes it from sibling tools like get_my_competitor_ads and search_competitor_ads by scoping to the user's watchlist.

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

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

The description explicitly prescribes a use case: 'Use for "what are my competitors doing lately?"'. It gives clear context but does not mention alternatives or when not to use the tool, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It explicitly states 'Facts only, no predictions', which discloses a non-obvious behavioral trait. It also implies a read-only operation by focusing on listing and ranking, and mentions ranking by recent spend, adding value beyond the schema.

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

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

The description is concise, with a clear list of metrics and a single-purpose statement. Every sentence adds value, and it is front-loaded with the core action and scope, followed by useful context and a clarifying caveat.

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

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

Given the tool has 2 optional parameters, no output schema, and no annotations, the description adequately covers the purpose, key return fields, and behavioral note ('Facts only, no predictions'). It lacks explicit details on how the data is filtered or sorted beyond 'ranked by recent spend', but for a list tool this is sufficient.

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

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

Schema description coverage is 100%, as both 'days' and 'limit' have descriptions. The tool description adds no additional parameter meaning beyond what is already in the schema, so a baseline of 3 is appropriate; it doesn't need to compensate for gaps.

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

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

The description specifies the verb 'List' and the resource 'the marketer's OWN ads', clearly distinguishing it from sibling tools like search_competitor_ads and get_my_competitor_ads by emphasizing ownership. It also lists the performance metrics returned and mentions the 'Ad Library YOUR ads corpus', which clarifies its unique scope.

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

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

It clearly indicates this is for the marketer's own ads and notes it powers the Ad Library 'Your ads' corpus, providing context for when to use it. However, it does not explicitly state when not to use it or mention alternatives for competitor ads, though sibling names suggest that distinction.

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?

No annotations are provided, so the description carries the burden. It mentions 'Quick lookup' implying a read operation, and lists the data returned. However, it doesn't disclose any behavioral traits like whether it triggers a sync, whether it requires prior data sync, or what happens if the ad isn't found. The description is adequate but not rich in 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?

The description is two sentences: the first states the purpose and data returned, the second gives example queries. It's front-loaded with the key information and has zero waste. Perfectly concise.

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

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

For a simple lookup tool with 2 parameters, 100% schema coverage, and no output schema, the description is quite complete. It covers what the tool does, what data it returns, and example usage. The only gap is not explaining the return format, but since there's no output schema, a brief note on return structure would help. Still, for the tool's simplicity, it's nearly 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 100%, so the schema already documents both parameters (days and ad_name_or_id). The description adds the example usage patterns but doesn't add meaning beyond the schema. The 'partial match' and 'default 7, max 30' are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Quick lookup of a specific OWN ad's performance' and lists the specific metrics returned (spend, CTR, CPC, impressions, status, genome tags). It also provides example queries ('what's the CTR on [ad]?', 'how is [ad] performing?'), which makes the purpose unmistakable. The emphasis on 'OWN' distinguishes it from competitor-focused sibling tools.

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

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

The description gives clear usage context with example questions, and the 'OWN' qualifier implies it's for the user's own ads, not competitors. However, it doesn't explicitly state when NOT to use this tool or name alternative tools (e.g., list_my_ads for a broader view, or search_competitor_ads for competitor ads). The guidance is clear but lacks explicit 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?

No annotations are provided, so the description carries full responsibility. It discloses the memory side effect ('remember it'), the non-download behavior ('reads the header of the copy we already hold, no download, no third-party CDN'), and the sentinel null semantics ('UNMEASURED, never zero'). This is significantly more transparent than typical minimal descriptions.

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

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

The description is three sentences, front-loads the core purpose, and each sentence earns its place: measurement action, operation mechanism, null meaning, and use context. There is no filler or redundant restating of the tool name.

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

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

For a one-parameter tool with no output schema and no annotations, the description is unusually complete. It tells the agent what is measured, how it is done, what is not done (no download/CDN), what is returned, what null means, what side effect occurs, and when to apply 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?

With only one parameter and 100% schema description coverage, the schema already explains asset_id as 'The watch asset id of the public ad to measure.' The description reinforces that the ad must be PUBLIC but does not add new meaning to the parameter beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Measure how long a PUBLIC ad's creative actually runs, in seconds, and remember it.' It also names the return shape ({duration_seconds}) and clarifies the measurement scope. This distinguishes it from sibling tools that center on performance, comparison, or deconstruction.

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 explicit timing guidance: 'Use before acting on an ad's length when the corpus says its duration is unknown.' It also scopes the tool to PUBLIC ads and explains exceptional cases through null. It does not explicitly name a fallback or alternative tool, so it stops just short of the strongest 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?

With no annotations, the description carries the full responsibility for disclosing behavior. It reveals that the tool performs semantic search, returns facts with validity windows and receipts, excludes superseded facts by default, and requires quoting valid_from/invalid_at to avoid stale information. This is transparent about the core behavior and edge cases. It doesn't mention auth or side effects, but for a read-only search tool that is acceptable. The phrase 'receipts' hints at output but could be clearer.

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 four sentences long, each providing distinct value: it poses the purpose as a question, defines the tool's function, details the superseded-fact behavior, and gives a usage directive. It is front-loaded with the question that immediately clarifies intent. While it could be slightly tightened, it is not verbose and every sentence earns its place.

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

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

For a tool with no output schema and no annotations, the description covers the essential aspects: purpose, usage timing, and subtle behavior around validity windows and history. It does not describe the return format in detail (only mentions 'receipts'), nor does it explain the limit parameter, but these are minor gaps. The description is sufficient for an agent to invoke the tool correctly for its intended use case.

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 75%, so three parameters (query, as_of, include_history) have descriptions. The tool description adds meaning beyond that by explaining the concept of validity windows and the 'include_history' behavior, which clarifies the purpose of as_of and include_history. The limit parameter lacks a description in the schema and is not addressed in the tool description, which is a minor gap. Overall, the description enhances parameter understanding significantly.

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

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

The description starts with a clear question 'What has this brand's marketer already decided, corrected or rejected?' and then defines the tool as 'Semantic search over the brand's own memory, returning facts with their validity windows and receipts.' This is specific (semantic search over memory), identifies the resource (brand's memory), and distinguishes from sibling tools like 'get_brand_context' or 'get_account_memory' by focusing on past decisions and validity windows.

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

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

The description explicitly states 'Call it before proposing anything the marketer may have already ruled on,' which tells the agent when to use it. It also explains when to include history ('unless you ask for history') and instructs to 'quote valid_from/invalid_at rather than presenting an expired fact as current,' providing clear behavioral guidance. No alternatives are named, but the context makes it obvious this is the right tool for checking past rulings.

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

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

The description discloses the supersede behavior: recording the same relation with a different fact automatically replaces the old fact, turning it into history. This is a critical behavioral trait not apparent from the schema. With no annotations provided, the description fully carries the burden of explaining side effects and persistence 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?

The description is a single paragraph but well-structured with clear guidance on format, usage, and exclusion. Every sentence adds value: purpose, evidence format, supersede behavior, and usage boundaries. It is appropriately concise for the complexity of the tool.

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

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

The tool has 9 parameters but the description provides enough context to understand the required inputs (subject, relation, fact) and the optional ones (quote, object, artifact_ref). It explains the return behavior implicitly (the fact will be read back later). With no output schema, the description adequately covers the essential context 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?

The schema covers 78% of parameters with descriptions, but the description adds critical semantics: the fact field is 'what you will read back later', quote is 'marketer's own words', and the relation format is 'lowercase and stable'. The description also explains the subject+relation+object structure, which adds meaning beyond the schema's individual field descriptions.

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

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

The description clearly states the tool's purpose: to record durable facts about the brand learned from the marketer. It specifies the verb ('record'), the resource ('something durable about THIS brand'), and differentiates from siblings by emphasizing persistence and the supersede behavior. It also gives concrete relation format examples.

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

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

The description explicitly states when to use it ('when the marketer tells you something that should still be true next session') and when not to use it ('do NOT use it for chit-chat or for anything already in the brand context'). This clear usage context helps the agent decide between this and other saving tools like save_context_note or save_brand_truth.

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

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

With no annotations provided, the description carries the behavioral burden. It explains what constitutes a valid brand truth and instructs the agent to capture words verbatim and confirm the note to the user. It could more explicitly state whether the tool overwrites or appends, but for a simple save operation it is reasonably transparent.

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 longer than minimal but every section earns its place: definition, kind breakdown, usage separation, and verbatim instruction. It is front-loaded and well organized, though the examples could arguably be condensed without losing much.

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 save tool with no output schema, the description provides all essential context: what to call it for, what qualifies, how to invoke it (verbatim), and the expected follow-up interaction with the user. It was self-contained and clear.

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

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

The input schema already documents both parameters fully, providing 100% coverage. The description adds value by elaborating the meaning of each kind with realistic examples and reinforcing the verbatim requirement for 'statement', going beyond the schema's minimal wording.

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 ('Capture') and resource ('structural business truth'), then defines four clear kinds with concrete examples. Differentiates itself from the sibling save_context_note by explicitly saying one-off plans go there.

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

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

Tells the agent exactly when to use it: ONLY for durable business truths that shape the slate. Explicitly contrasts with 'NOT one-off plans' and redirects those to save_context_note, giving an alternative.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses key behavioral traits: saving verbatim, never rewriting words, and telling the user after saving that the note can be reviewed/removed in Brand. While it doesn't discuss permissions or side effects, the essential behavior is clearly communicated.

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

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

The description is dense but every sentence earns its place: the core action, the exclusions with alternatives, and the post-save behavior. It is front-loaded with the primary action and uses examples to make the verbatim requirement unambiguous.

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 2-parameter tool with no annotations and no output schema, the description is complete. It covers purpose, usage exclusions, named alternatives, storage behavior, and post-save user communication, leaving no significant gap in understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by emphasizing 'VERBATIM' and 'Never rewrite their words,' which clarifies the intended use of the text parameter. The source parameter is adequately described in the schema's enum descriptions.

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

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

The description states a specific verb and resource: 'Save a one-off correction or preference the marketer tells you to their context ledger, VERBATIM.' It further distinguishes from siblings by explicitly excluding dated plans (save_plan) and durable truths (save_brand_truth), making the tool's purpose unmistakable.

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 explicit when-to-use criteria and exclusions: NOT for questions/small talk, NOT for dated plans (use save_plan), NOT for durable truths (use save_brand_truth). This provides clear guidance on when to select this tool over its siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains important behaviors: requires a date, must use title verbatim, should read the date back to the user for confirmation, and the optional nature of ends_on. However, it doesn't specify the return value or side effects (e.g., does it overwrite existing plans?), but given the tool is less complex and the key behavioral traits are covered, a 4 is warranted.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds value—examples, parameter instructions, and exclusion rules. It fits entirely in a few sentences without redundancy.

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

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

Given no output schema and a relatively simple 4-parameter tool, the description is complete: it defines input requirements, usage criteria, and confirmation behavior. The interdependency with other save tools (save_context_note, save_brand_truth) is clarified, and the schema covers all parameters.

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

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

Even though schema description coverage is 100%, the description adds significant meaning beyond the schema: it emphasizes that `title` must be verbatim, and `starts_on`/`ends_on` must be ISO dates, and clarifies the optionality of `ends_on`. It also explains how `kind` helps categorize but doesn't add much beyond the enum values. Overall, this goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool captures a 'DATED upcoming plan' with a specific verb ('Capture') and resource, and distinguishes it from siblings like save_context_note and save_brand_truth by specifying what qualifies (dated plan) vs not (vague intentions, durable truths).

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 when to use (for dated upcoming plans with lead time) and when not to use (for vague intentions or durable truths), naming the alternative tools (save_context_note and save_brand_truth). Provides clear examples and instructions for handling date ranges.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It states what the tool returns, but does not explicitly mention that it is a read-only operation, any rate limits, or potential side effects. It does not contradict anything, but the lack of explicit safety or limitation notes leaves some ambiguity, though a search tool is typically non-mutating.

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

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

The description is concise, consisting of three short sentences that each contribute value: purpose, output, and usage. There is no redundant or filler content, and the information is well-organized and front-loaded. It strikes an ideal balance between brevity and informativeness.

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 that the output schema is not provided, the description appropriately mentions key return fields (hook types, creative styles, run duration) to give an idea of the result. It covers the main purpose and usage, and the parameter schema is detailed. However, it does not mention potential pagination or any limitations beyond the max limit, leaving minor gaps but overall sufficient for a search 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?

The schema already provides clear descriptions for all five parameters (limit, industry, hook_type, brand_name, creative_style), so the description adds little beyond what is already known. The baseline for full schema coverage is 3, and the description does not enhance parameter understanding or mention any additional constraints or relationships.

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

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

The description clearly states the verb 'Search' and the resource 'the ad library for competitor ads', making the purpose obvious. It also distinguishes this search tool from sibling tools like get_competitor_ads or get_competitor_channels by focusing on broad search and filtering. The mention of return fields (hook types, creative styles, run duration) further clarifies its intent.

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

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

The description provides explicit usage scenarios ('analyze competitor creatives, find inspiration, or see what a brand is running'), which guides when to employ it. However, it does not explicitly state when not to use it or compare it directly to alternatives, though the context of sibling tools implies it is for search rather than specific retrieval. This is clear but lacks explicit negative 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?

With no annotations provided, the description must carry the burden of disclosure. It discloses the enrichment data (days-running, spend range, audio, variations) that the tool returns, and the verb 'search' implies a read-only operation. However, it does not explicitly state that it does not modify any state or mention any side effects. Given the context of a search tool, this is adequate but not fully comprehensive.

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

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

The description is two sentences, front-loaded with the primary purpose, and every phrase adds value. It efficiently conveys the resource, enrichment, and usage context without any redundant words or filler.

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

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

For a simple search tool with two optional parameters and no output schema, the description is quite complete. It explains the purpose, usage context, and key enrichment fields. It doesn't detail return structure beyond the enrichment list, but given the simplicity and the schema descriptions, it suffices. It lacks explicit mention of ordering or edge cases, but these are not critical for a search 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 100% since both 'limit' and 'brand_name' have descriptions. The tool description adds no additional meaning about these parameters—it only mentions enrichment features and usage context, not how the parameters affect results. This meets the baseline of 3 when schema covers everything.

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 identifies the resource (the marketer's own saved swipe file) and action (search), and explicitly distinguishes it from competitor-focused tools by emphasizing 'OWN saved swipe file' and 'the marketer themselves has saved/admired.' This directly separates it from sibling tools like 'search_competitor_ads' and 'get_my_competitor_ads'.

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 provides explicit guidance: 'Use to ground a question in what the marketer themselves has saved/admired.' This tells the agent when to use it (grounding in personal saved ads) but does not explicitly name alternatives or state when not to use it. The implication of 'OWN' differentiates it from competitor ad searches, but no direct exclusions are given.

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

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

The description explicitly says 'Read-only — never writes to Meta', which is a strong behavioral guarantee. Since no annotations are provided, this is crucial. It also mentions that it queues the sync and that ads land a few minutes later, setting expectations about asynchronous behavior. It lacks some details like rate limits or failure modes, but given simple scope, it's good.

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

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

The description is concise, only 3 sentences. It front-loads the action ('Queue a read-only sync'), then gives usage context, then timing and safety. Every sentence adds value, no fluff.

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

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

Given there are no parameters, no output schema, and no annotations, the description does a good job covering the key facts: asynchronous execution, read-only guarantee, and where results appear. It could mention what happens if Meta is not connected (likely an error), but the 'when to use' condition covers that implicitly. Otherwise, it's complete for a simple action.

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 are zero parameters, and the schema coverage is 100% (vacuously). The description explains that it syncs the user's own ads, an implicit parameter (the user identity) that is not in the schema. It doesn't need to describe parameters because there are none. Baseline for 0 params is 4, and the description appropriately mentions the scope (user's own).

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

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

The description is very specific: it queues a read-only sync of the user's own Meta ads and insights, exactly matching the tool name 'sync_my_ads'. It also distinguishes itself from sibling tools by explicitly targeting the user's own ads, not competitors' ads (e.g., search_competitor_ads, get_my_competitor_ads).

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

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

It clearly states when to use: when the user's ad library looks empty or stale and Meta is connected. It also implies when not to use (if Meta is not connected) and differentiates from sibling tools that focus on competitors. It points to a related tool (list_my_ads) for seeing results, providing useful navigation.

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