Niche — Editorial Intelligence

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

The description discloses synchronous blocking behavior for text generation, idempotency for existing cells, credit cost estimation via estimate_only, and error codes. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds behavioral context without contradiction.

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

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

The description is detailed and front-loaded with purpose, but somewhat lengthy. Every sentence adds value, but could be slightly more concise. Structure is logical, covering use case, behavior, and error handling.

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

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

The tool has no output schema, but the description explains response fields (next_step, copy_lineage) and covers errors, idempotency, and synchronous behavior. It is complete for a complex 4-parameter tool.

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

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

Schema coverage is 75%, and the description adds significant context: it explains valid cells reference, remove_cell behavior, and estimate_only purpose. It also clarifies text vs asset cell behaviors beyond schema descriptions.

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

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

The description clearly states the tool adds an output cell to a session at CP3, distinguishing it from siblings by specifying the precondition and action. It also mentions removal via remove_cell, providing a specific verb and resource.

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 ('when the user picked a small initial cell set...and now wants another surface'), covers preconditions (CP3), and mentions error cases (400 if pre-CP3, 422 if invalid cell). It implicitly references alternatives like niche_render_image_card and niche_render_reel but does not explicitly contrast with all siblings.

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

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

Annotations only show mutability; description adds that it returns immediately with status cp2_generating, that polling is needed, and mentions capping and metering. No contradictions.

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

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

Well-structured with clear sections, but slightly verbose. Could be trimmed without losing clarity, but still effective.

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?

Comprehensive for a tool with no output schema: explains return format (angles array), states polling needed, and covers edge cases like null recommended_angle_id.

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

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

Even with 80% schema coverage, description adds meaningful context for custom_framing and regenerate parameters, including conditions and behavior. Lens is clarified as only read when regenerate=true.

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

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

The description clearly states it picks a story from the discovery slate and surfaces the strongest angles, which is a specific verb-resource combination. It is distinguished from sibling tool niche_draft_direct by explaining when to use custom_framing instead.

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 explains when to use custom_framing (vs draft_direct), when to use regenerate, and that polling is required. Provides clear context and 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?

Adds significant context beyond annotations: describes mutation (attaches image), undo capability, server behavior for chunks (verification, resend logic), and warnings about image aspect fit. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

The description is structured with numbered input modes and clear sections, but it is quite verbose. However, the detail is necessary given the tool's complexity. Front-loaded with purpose.

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

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

Comprehensive coverage of all aspects: input modes with rationale, preconditions, error handling, integrity checks, and side effects (undo). Although no output schema, the description explains the result (image attached, published).

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 with 83% schema coverage, the description enriches parameter meaning with detailed explanations for each input mode, chunking mechanics (size, sha256, sequencing), and how to use upload_ref. The description compensates for the remaining uncovered parameters with clear 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 attaches a user-supplied image to a post cell, distinguishing it from sibling tools like niche_render_image_card (AI-generated) and niche_add_output (prerequisite). The verb 'attach' is specific and the resource is well-defined.

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 when-to-use guidance for each input mode (upload_ref > image_url > image > image_chunk fallback), states prerequisite (cell output must exist via niche_add_output), and explains when not to use (e.g., for AI-generated images). Alternatives and exclusions are clear.

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

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

Annotations declare readOnlyHint=true, so no destructive actions. The description adds beyond annotations by detailing that the chain is computed from current state (is_already_set derived from BrandKit and BrandProfile), and the agent can ask in any order. It does not contradict annotations.

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

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

The description is detailed and well-structured, starting with the core return value, then usage context, tiers, per-question attributes, and final usage notes. While lengthy, it is front-loaded and each section serves a purpose. Minor redundancy could be trimmed.

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

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

Given the complexity of a guided setup with multiple tiers and state-dependent filtering, the description is comprehensive. It explains the intent, prompt_hint fallback, applies_to_field mapping, and is_already_set computation. No output schema exists, but the description sufficiently covers what the agent receives and how to interpret it.

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

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

Schema description coverage is 100%, but the tool description adds meaning: explains that brand_id influences is_already_set computation by reading the persisted BrandProfile, and include_filled controls gap filtering. This provides context beyond the schema's basic definitions.

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 returns a structured question chain for brand kit setup, specifying the entries' structure (intent, prompt_hint) and how they map to fields. It distinguishes from sibling tools like niche_brand_kit_update and niche_brand_profile_set by focusing on guiding the user through a Q&A sequence rather than direct updates.

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 agent is helping a new user set up Niche and wants a predictable, brand-aware Q&A sequence instead of improvising.' Describes tiered approach (Tier 0-3) based on URL ingest availability, giving clear guidance on flow selection. Also advises that the agent can skip questions if already answered.

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

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

Description discloses additive nature, idempotency, overwrite rule, async behavior with polling, and handling of duplicates. No contradiction with annotations; adds significant context beyond readOnlyHint=false and destructiveHint=false.

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

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

Well-structured with clear sections, front-loaded with purpose and core behavior. Slightly verbose but every sentence adds value, earning its place given the tool's complexity.

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?

Provides complete guidance on async pattern, polling workflow, return structure (ingest_id, status, eventual report), and edge cases (slow URL, incomplete voice pass). No output schema, but description compensates fully.

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

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

Parameters are fully explained in schema (100% coverage), and description adds interactive semantics: text URL precedence, files classification, replace confirmation requirement, brand_id for separate profiles, brand_name for new slots.

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: auto-populate BrandKit from files, URL, or text. It distinguishes from sibling tools like niche_brand_kit_update and niche_brand_kit_guided_setup by specifying the ingest operation.

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 brand assets are in scope) and when not to (if brand kit already has identity for different brand). Provides alternatives (create separate brand, niche_brand_kit_ingest_status) and warnings about re-calling.

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

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

Adds polling behavior, status definitions, failure details, and expiration beyond the readOnlyHint and destructiveHint annotations, which already indicate safety.

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

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

Extremely concise with efficient bullet-like format, front-loading purpose and providing all needed info in two sentences.

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

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

Comprehensive for a polling tool with one parameter and no output schema, covering all statuses and expiration. Minor gap: doesn't explicitly state that response varies by status, but it's implied.

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% for the single parameter; description restates its source but adds no new semantic value, meeting 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?

Clearly states it polls the result of an async ingest, distinguishing it from the sibling niche_brand_kit_ingest which initiates the process.

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 instructs to pass the ingest_id from the ingest call and describes three statuses. Provides expiration timeout (30 min) but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare write operations, but the description adds extensive behavioral context: partial updates, list replacement, diff in response, soft archive, default brand restriction, published history requirement, and archive_scope batch archiving, all beyond annotation hints.

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

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

The description is well-structured, front-loaded with the primary purpose, and each sentence adds necessary detail. No redundant or vague statements.

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 26 parameters and no output schema, the description provides enough context for correct tool selection and invocation, including archiving caveats and field update behavior. A brief mention of response format would improve completeness, but overall quite thorough.

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

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

Schema coverage is 50%, and the description explains key parameters like archive, acknowledge, archive_scope, and general behavior for lists. However, several parameters (e.g., accent, logo_url, primary_bg) are only in the schema, so the description doesn't fully compensate. Still, the archiving details add significant value.

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 'Set specific BrandKit fields by name' and distinguishes from sibling tools like niche_brand_kit_ingest and niche_brand_kit_guided_setup, making the purpose specific and unambiguous.

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

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

Explicitly says when to use this tool: 'Use after niche_brand_kit_ingest fills the easy stuff, or to commit values the user answered through niche_brand_kit_guided_setup.' Also explains archiving scenarios and behavioral nuances.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: non-modifying behavior, dual listing/retrieval, and specific return fields (full profile JSON, timestamps, sync status). No contradictions.

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

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

Three sentences with no wasted words. The main action is front-loaded, and each sentence adds distinct value: what it does, when to use, and what it returns.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, usage, return fields, and variations. No gaps.

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

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

Input schema has 100% description coverage for the single parameter. The description reinforces the optional nature and adds meaning by explaining the dual behavior (read one vs. list all), going beyond what the schema provides.

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

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

The description uses a specific verb ('read back') and resource ('persisted brand profile'), clearly distinguishes from the sibling tool 'niche_brand_profile_set', and lists concrete use cases (confirm, check, inspect).

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 the tool (confirm, check, inspect) and notes the alternative listing behavior when omitting brand_id. While 'when not to use' is implicit, the guidance is clear for a read-only retrieval tool.

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

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

Annotations only indicate non-read-only, non-destructive. Description adds significant context: tiered validation (error/warn/info), conflict handling with brand kit, overwrite behavior on re-set, and error response with schema template. This goes well beyond annotations.

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

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

Description is well-structured: introduction, required fields, validation, then detailed profile breakdown. Front-loaded with purpose. However, it is somewhat verbose, with lengthy explanations of profile sections that could be more 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?

Given no output schema, description covers input semantics, validation, conflicts, and error handling thoroughly. It lacks explicit return value structure (though mentions lints and conflicts). For a complex tool, it is reasonably 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 covers all 3 parameters (100%), but description adds deep meaning, especially for the nested 'profile' object, explaining each section (identity, voice, lexicon, framing, etc.) and validation details. It even mentions error responses return a full schema template, eliminating need for separate discovery.

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?

Title and description clearly state the tool sets or updates a brand profile, with specific verb ('set or update') and resource ('brand profile'). It differentiates from siblings by detailing the profile's use across pipeline stages, contrasting with read-only get or guided setup 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?

Description provides explicit use cases: persist profile from docs for future runs, or update voice/banned terms. It explains fallback behavior and validation lints. Missing explicit 'when not to use' or comparison to alternatives like niche_brand_kit_guided_setup, but still clear context.

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

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

The description goes beyond annotations (destructiveHint=false, readOnlyHint=false) by detailing the asynchronous polling mechanism, the immediate return with status=cp3_generating, the trust data structure in outputs, and the estimate_only behavior. No contradictions with annotations.

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

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

The description is front-loaded with the core action and outcome. It includes necessary detail on polling and trust data, but the sentence structure is slightly run-on. Every sentence adds value, though compactness could be improved.

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 fully covers the asynchronous response pattern, polling requirement, and trust data fields. It also describes the estimate_only mode, leaving no significant behavioral gaps for a tool with three parameters.

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

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

Schema coverage is 67% (angle_id and estimate_only have descriptions; session_id lacks one). The description adds meaning for estimate_only by explaining cost preview without generation, and reinforces angle_id's role. It compensates for schema gaps with behavioral info but doesn't detail session_id.

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

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

The description clearly states the tool creates platform-native drafts by locking an angle. It differentiates from siblings like niche_draft_direct and niche_draft_revise by specifying the 'lock the chosen angle' step, establishing a distinct purpose.

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

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

The description implies this tool is used after the story and angle are decided ('downstream payoff'), providing clear context. However, it does not explicitly contrast with alternatives like niche_draft_direct or niche_draft_revise, only implying the workflow sequence.

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

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

Annotations are consistent (readOnlyHint=false, destructiveHint=false). Description adds important behavior: returns session_id in <2s, polling needed for results, image credit costs, and brand binding for voice. No contradictions.

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

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

Well-structured: front-loaded purpose, then usage contrast, then parameter details, then workflow. Slightly long but every sentence is necessary. Minor redundancy in brand binding mention.

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

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

Despite no output schema, description explains return value and subsequent polling. Covers all 8 parameters with usage notes, defaults, and constraints. Provides workflow context for successful invocation.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining that at least one of take/source_url/source_text must be provided, and clarifies the difference between take and repurposing sources. Also adds context on image credit costs and verify usage.

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

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

Title explicitly states 'Draft directly (no scan, BYOC)' and description clarifies it is for drafting the creator's own take or product, distinguishing from niche_signal_scan. Verb and resource are clear.

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

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

Explicitly states when to use (product-led or BYOC work), provides examples, and contrasts with niche_signal_scan for 'what's worth writing' vs 'write this exact thing'. Also gives guidance on required inputs and brand binding.

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 thoroughly discloses behavioral traits beyond annotations: declares commit as 'the only irreversible action', explains dry_run returns payload without filing, verifier blocks prevent publishing, not-connected returns connect_url, scheduling dispatches automatically, cancellation is idempotent, and acknowledge_surfaced is required when claims are surfaced. Annotations include destructiveHint=true, and the description aligns perfectly, adding rich 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 long but well-structured with clear sections (dry_run default, commit flow, preview requirements, scheduling, platform selection). It front-loads the most critical behavior (dry_run=true default) and maintains logical flow. While every sentence adds value, the length could be slightly reduced without losing clarity. Still, it is effectively organized.

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 (7 parameters, destructive action, multiple edge cases like verifier blocks, not-connected accounts, scheduling, and idempotency), the description covers all aspects comprehensively. It explains response fields (status, resolved_cell, connect_url) even without an output schema. No gaps remain for an agent to safely invoke 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 71% schema description coverage, the description adds significant meaning beyond the schema. For platform, it explains the preferred cell string format and family coercion. For idempotency_key, it clarifies it's required for commit and returns prior result. For scheduled_for, it specifies ISO-8601 future datetime and that long-form has no scheduled path. For acknowledge_surfaced, it details when it's required. The description compensates for schema gaps and enriches all parameters.

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

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

The description begins with 'Publish a single output to its platform', which clearly states the verb (publish) and resource (single output/draft). It distinguishes this from siblings like niche_draft_create and niche_draft_revise by focusing on the publish action. The detailed explanation of dry_run vs commit further clarifies the purpose.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: defaults to dry_run=true for previewing; set dry_run=false with idempotency_key to commit; present preview to human before committing; handle verifier blocks by clearing them; handle not-connected social by sending user to connect. It also explains scheduling and cancellation, and prefers exact cell strings over family names. This covers all major 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?

Annotations readOnlyHint=false and destructiveHint=false indicate mutation but not destruction. The description adds behavioral details: no-change behavior with status, diff response, and that angle/story changes invalidate verifier trust block (though that's for another tool). No contradictions with annotations.

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

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

Description is detailed but well-structured: starts with core function, lists fields, then special behaviors. Every sentence adds essential info, though slightly verbose for some (e.g., slide_patches details could be shorter).

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 (7 params, nested objects, no output schema), the description covers edge cases (no-change, slide_patches modes, hook variant splicing), response format (diff array), and relationship to sibling tools. Very 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 covers 86% of parameters. Description adds context: 'apply_hook_variant_index' is cheaper than manual edit, slide_patches has two modes (in-place vs structural) with warnings, and regenerate_hooks is metered. Provides meaning beyond the schema.

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

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

The description clearly states the tool 'applies the values you pass to a specific output', naming specific fields (caption, hashtags, script_updates) and contrasts with niche_angle_propose for angle/story changes, distinguishing itself from siblings.

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

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

Explicitly states when not to use the tool ('Angle and story changes still go back through niche_angle_propose'), explains the no-change case, and describes the diff response for user feedback.

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

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

Annotations indicate openWorldHint=true and destructiveHint=false. The description adds significant behavioral context: it is non-blocking with immediate session_id return, requires polling, explains the two-phase process (slate, then synthesis), and notes fact-verification. It also states that both engine and web app return identical results. No contradictions with annotations. The description adds value beyond the structured fields, earning a 4.

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

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

The description is relatively long but well-organized: opening with core purpose and examples, then detailing the async flow, then parameter-specific notes. It is front-loaded with key info (non-blocking, what to poll). While every sentence adds value, some details (e.g., 'Niche (nicheangle.com)') could be integrated more concisely. It is appropriately sized for the complexity, so a 4.

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

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

With 11 parameters and no output schema, the description must cover usage flow, polling, and return expectations. It does: session_id, polling interval, status 'cp1_awaiting_story', stories array, synthesis fields, and edge cases like synthesis:'none'. It also explains the non-blocking nature and idempotency. While it doesn't detail every possible response field (since no output schema), it provides enough context for correct invocation. Slight room for more on error handling, but overall complete for the task.

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?

Input schema has 100% description coverage, but the tool description enriches parameter meanings substantially. For example, it explains `lens` enum values in detail ('emerging' inverts saturation), `window` with mapping from 'this week' to 'week', and `idempotency_key` for billing dedup. It also links `brand_id` to `niche_whoami`. This goes well beyond the schema descriptions, providing actionable guidance, so a 5 is justified.

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

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

The description explicitly states the tool is for 'Niche research and analysis' to answer 'an analyst-shaped question' and provides concrete examples like 'the 10 biggest developments in X this week'. It clearly defines the deliverable as a ranked slate with narratives, distinguishing it from tools like niche_angle_propose by noting that narratives can be turned into posts using that sibling. This meets the 5-point standard of a specific verb+resource that differentiates from siblings.

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

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

The description gives explicit 'Use for:' examples and warns 'do not synthesize your own narratives over the slate, present these.', which is a when-not instruction. It also explains when to use synthesis:'none' vs other values. However, it does not explicitly list alternative tools for related tasks (e.g., niche_signal_scan), only directing to niche_angle_propose for post creation. This is clear usage context but lacks explicit exclusions for all siblings, so a 4 is appropriate.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds valuable behavioral context: return order (newest-first), detailed outcome enum, and clarification about 'failed' status not always being error. No contradictions.

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

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

Description is well-structured with two paragraphs: first explains when to use and basic returns, second gives detailed outcome guidance. Could be slightly trimmed, but overall concise and effective.

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

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

With no output schema, description adequately covers return fields and outcome semantics. Given 6 parameters mostly self-documenting, the description provides sufficient context for effective tool selection and 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?

Input schema has 100% description coverage for all 6 parameters, so description does not need to add meaning. The description adds general output context but does not enhance parameter understanding beyond schema.

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

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

Description uses specific verb 'Enumerate' and resource 'user's recent sessions', lists return fields, and states use cases (lost session_id, find in-flight session). Clearly distinguishes from sibling tools like niche_session_state which targets a single session.

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 (lost session_id, find in-flight session) and provides guidance on interpreting outcome vs status. Lacks explicit when-not-to-use or direct alternatives, but the context is clear enough.

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

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

Annotations only indicate read=false, destructive=false. The description adds critical context: async behavior for 'photo'/'design' backgrounds (polling needed), credit costs, idempotency (repeat call no-op), error states, and synchronous/free alternatives. This fully compensates for the sparse annotations.

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

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

The description is long but well-structured with clear headings for scopes and background types. Each sentence earns its place given the tool's complexity. A small amount of redundancy (e.g., repeating 'free, instant' for brand_color and svg) is acceptable for 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?

No output schema exists, so the description must compensate. It explains that async scopes return a status to poll, mentions error conditions, and describes credit costs. It does not detail every return field but provides sufficient guidance for an agent to handle 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%, so baseline is 3. The description adds significant extra meaning: for each parameter it explains when it is required, effects, default behaviors, and interaction with scope. For example, 'background' details each enum option's cost, synchrony, and use cases. This elevates beyond the bare schema.

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

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

The description states a specific verb ('Render') and resource ('image card'), and clearly distinguishes four scopes ('full', 'recomposite', 'restore', 'reframe') that cover creation, editing, reverting, and aspect variation. This differentiates it from 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 explicitly states when to use each scope ('full' requires background, 'recomposite' for free text edits, etc.) and when not to (e.g., errors like render_not_ready before CP3). It also provides alternatives through the background parameter options.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds that the tool is idempotent on video output (replaces prior render), specifies cost (~350 credits), and lists error codes. It explains what each scope does and what is reused, providing clear 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 lengthy due to complexity but well-structured. It front-loads the core purpose and scope, then details options, errors, and cost. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given 20 parameters and no output schema, the description covers purpose, scope, options, errors, cost, and behavioral traits. It lacks explicit output format details (e.g., download URL), but overall provides sufficient context for an agent to use 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?

With 100% schema coverage, baseline is 3. The description adds context by explaining scope behaviors, the difference between 'length' and 'target_duration_sec', and that 'caption_sync_mode' is ignored when captions disabled, adding meaning beyond the schema.

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

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

The description clearly states the tool renders a 9:16 vertical reel at CP3, listing components (stills, voiceover, etc.) and duration range. It distinguishes from sibling tool niche_render_image_card, which renders image cards.

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 details scope options ('full', 'recomposite', 'endcard', 'beat:N') with clear conditions for each, including when script changes require 'full'. It provides context on when to use each scope, but does not explicitly exclude other tools for alternative tasks.

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

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

Discloses that the operation is instant, free, copies static_urls, and is idempotent. Aligns with annotations (readOnlyHint=false, destructiveHint=false) and adds important detail beyond them.

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

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

Concise at ~100 words, front-loaded with purpose, then usage, then behavior. Each sentence adds value with no redundancy.

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

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

Given the simplicity of the tool (3 params, no output schema), the description covers purpose, usage context, prerequisites, behavior, and idempotency. Adequate for an agent to select and invoke 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 covers 2 of 3 parameters with descriptions. The description adds context: from_cell must have rendered image, to_cell must exist, and suggests using niche_add_output if needed. Compensates for missing session_id description.

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

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

The description clearly states the tool copies an existing image between cells, distinguishing it from niche_render_image_card which generates new images. The verb 'reuse' and resource 'image across cells' are specific and distinct from siblings.

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

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

Provides explicit guidance: use when user wants the same image on another surface, not when a new image is needed (alternative named). Also includes prerequisites like cells must exist and source must have a rendered image.

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

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

Goes beyond annotations by detailing idempotency, credit release/refund policies, and that committed work remains charged. Annotations only indicate destructiveHint=true; description adds critical behavior 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?

Multiple sentences but each adds value. Front-loaded with purpose, then behavioral details, usage guidance, and credit policy. Could be slightly more compact but is well-organized.

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

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

Covers all important aspects: state change, orchestrator stop, slot freeing, idempotency, credit behavior. No output schema exists, but description addresses return value implicitly via state effects.

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 has 50% description coverage (only 'reason' has a brief description). The description adds that 'reason' is surfaced as session.error_message and defaults to 'cancelled by user', providing additional semantic value.

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 'Cancel a running session' and explains the effect (marks status=failed, stops orchestrator). It distinguishes from hard deletion via REST DELETE, making the purpose unambiguous.

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

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

Explicitly states when to use: 'to free a slot...' and contrasts with DELETE endpoint. Provides clear alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds behavioral context: it preserves traceability, outputs a standard editorial-calendar shape, and details the two formats. No contradictions.

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

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

Front-loaded with a concise summary, then structured into when-to-use, format details, and traceability benefits. Every sentence adds value; no wasted words.

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

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

Given no output schema and two parameters, the description fully explains the tool's purpose, usage, output formats, and traceability. It is complete for the tool's complexity.

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

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

Schema coverage is 50%; the description extensively explains the 'format' parameter with details on markdown and json outputs, and implies 'session_id' usage through traceability discussion. Adds significant value beyond schema.

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

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

The description clearly states the verb 'export' and the resource 'session', with specific details like preserving session_id and story_id traceability. It distinguishes from siblings by indicating its use case after niche_signal_scan.

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: 'Use after a niche_signal_scan when you want a metadata-rich content backlog instead of running individual pieces end-to-end.' It does not explicitly list when not to use, but the context is clear.

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

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

The description discloses important behaviors beyond annotations: it is idempotent ('reverting a session already at the target checkpoint returns the current state unchanged'), destructive (discards paid-for drafts), and requires acknowledgment for finished runs. The credit implications are also mentioned. Annotations already indicate destructiveHint=true, but the description adds valuable 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 concise with a clear structure: purpose, usage, parameter behavior, idempotency, and safety. Each paragraph adds distinct information. It could be slightly shorter, but no unnecessary repetition.

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 (3 parameters, no output schema), the description covers state transitions, side effects, and safety mechanisms. It explains the two revert targets and the discard confirmation flow. While exact return format is omitted, the description is sufficient for correct invocation.

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

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

Schema description coverage is only 33%, but the description adds meaning for the 'to' parameter by explaining the two enum values and their consequences. For 'acknowledge_discard', it clarifies the requirement for cp3/complete sessions. The 'session_id' parameter is not elaborated, but overall the description compensates well for low schema coverage.

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

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

The description clearly states the tool's function: 'Revert a session back to an earlier checkpoint.' It specifies the two targets ('story' and 'angle') and their effects, distinguishing it from related tools like niche_session_cancel or niche_session_state. The mention of 're-pick without starting a new scan' adds clarity.

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: 'when the user (or you) decided the picked story / angle isn't the right one and you want to re-pick without starting a new scan.' It provides context for both 'to' options and highlights the safety workflow for reverting finished runs. It does not explicitly exclude other scenarios but offers sufficient guidance.

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

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

Beyond the readOnlyHint annotation, the description explains that it is safe and cheap, details the return state (including sparse mode), and elaborates on the behavior of wait and wait_until parameters, including rate-limit warnings. It fully discloses the state machine and provides a status glossary.

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?

Although long, the description is well-structured and front-loaded with the core purpose. Each paragraph adds essential information without redundancy, and bullet points make key details scannable. Every sentence earns its place given the tool's complexity.

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

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

Given the tool's complexity (8 parameters, state machine, no output schema), the description covers all necessary aspects: return fields (including nested trust data), status glossary, poll loop recommendations, and parameter interactions. It is complete enough for an agent to use correctly.

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

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

With 100% schema coverage, the description still adds significant value: it explains the purpose of each parameter in context (e.g., view='status' for lean polling), clarifies aliases (wait_for for wait_until), and provides usage guidance (include_unpicked only with view='full').

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

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

The description clearly states it is a 'Universal poll endpoint' that reads the full current state of a session, with a specific verb (read) and resource (session state). It distinguishes itself from sibling tools by being a safe, cheap poll endpoint used for checking progress.

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 when to use ('Call this whenever you need to check progress'), recommends a poll loop with wait, and describes when to use view='status' vs 'full'. Also notes the alias niche_story_search and warns against rate limiting.

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 fully discloses the tool's behavior: it starts a long-running process, returns a session_id and initial status, and requires polling. It also explains that the brand profile is snapshotted at scan time, that profile_overrides are deep-merged, and that estimate_only returns cost without starting a run. This aligns with annotations (readOnlyHint=false, openWorldHint=true) and adds detail beyond them.

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

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

The description is detailed and well-structured, starting with a clear purpose, then explaining process, then parameter details. While it is lengthy, the complexity of the tool (12 parameters, nested objects, workflow) justifies the length. It is front-loaded with the key purpose and process.

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

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

Given the tool's complexity (12 parameters, long-running process, integration with brand profiles and polling), the description covers the workflow thoroughly. It explains the lifecycle (scan → poll → read slate), the role of brand_id and profile_overrides, and how to use estimate_only for cost estimation. No output schema exists, but it describes the return values (session_id and status) and directs the agent to poll niche_session_state.

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?

All 12 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds significant value beyond the schema by explaining the interaction between brand_id and profile_overrides, the behavior of recency_strict, the effect of estimate_only, and the polling behavior of thinking_budget. This justifies a higher score.

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 'story discovery' and distinguishes from content generation. It specifies the tool's role as the 'editorial-intelligence step before any writing.' The verb 'discover' and the explanation of returning a session_id and polling differentiate it from sibling tools like niche_draft_create or niche_angle_propose.

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

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

The description explains when to use this tool (story discovery) and provides context for brand profile usage and downstream polling. It implies that for content generation, other tools should be used. However, it does not explicitly exclude use cases or mention alternatives like niche_angle_propose for angle generation.

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

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

Adds substantial behavioral details beyond annotations: explains overwrite behavior (no-op on re-run unless overwrite=true), brand-scoping and fallback, and the threading into content generation. No contradiction with annotations.

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

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

Three focused sentences plus a clarifying paragraph on input shapes. Every sentence adds value, no redundancy. Well-structured for quick comprehension.

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

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

Despite no output schema, description explains return values (extracted primitives + diff). Covers repeated call behavior, brand fallback, and connection to generation. Complete for agent decision-making.

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

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

Schema coverage is 100%, and the description adds significant meaning for each parameter: url best sources, posts length and count, brand_id scope/fallback, archetype tagging, overwrite default behavior. Greatly enhances schema explanations.

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 extracts voice primitives and persists them to a VoiceProfile, with specific verbs (extract/persist) and resource. It distinguishes from sibling tools like niche_brand_profile_get/set by focusing on voice profile ingestion.

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 describes two input shapes (posts or url), when each is appropriate, and how conflicts are resolved. Does not directly compare to sibling tools, but purpose is unique enough that usage context is clear.

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

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

Discloses it is a read-only call, lists exact return data (tool names, count, account info, capability map bands, brand state). Annotations already mark readOnlyHint=true and destructiveHint=false; description adds valuable context about response structure and preconditions.

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 well-structured with front-loaded purpose and detailed breakdown of returns. Slightly long but each sentence adds value; could be trimmed slightly for conciseness.

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

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

Given the tool's role as an orientation tool with no output schema, the description comprehensively lists all returned components (catalog, account, capability map, brand state). No gaps for effective agent invocation.

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

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

Schema coverage is 100% with one boolean parameter already well-described in the schema. The description adds no extra parameter detail 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 clearly states it lists the full tool catalog, account info, capability map, and brand state. It uses a specific verb ('list') and resource ('tool catalog, account, capability map, brand state'), effectively distinguishing it from all sibling tools focused on specific actions like drafting or publishing.

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 advises 'Call it first to discover what's available, plan a session, and check credits before spending.' Provides clear when-to-use guidance with no ambiguity, though no explicit alternatives are given since it's unique.

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