Niche — Editorial Intelligence

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

The description goes far beyond the minimal annotations (readOnlyHint=false, destructiveHint=false). It discloses blocking behavior (~20-30s), idempotency, auto-attachment of branded cards for image cells, no auto-render for video/reel assets, next_step guidance, copy_lineage semantics, and error conditions (400 pre-CP3, 422 invalid cell). This is rich behavioral context that an agent needs to invoke correctly and set user expectations.

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 in clear paragraphs: purpose/usage, text vs asset behavior, next_step guidance, removal, and errors. Each sentence contributes meaningful information; no filler or repetition beyond the necessary emphasis on idempotency (which is important). For a tool with this complexity, the length is justified and front-loaded with the core purpose.

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

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

Despite having no output schema, the description fully explains what the response contains (next_step, copy_lineage) and covers all major behaviors: adding text/asset cells, blocking, idempotency, auto-rendering rules, removal, and error cases. Given the tool's complexity (4 params, multiple cell types, sub-operations), this description is complete and leaves no critical gaps.

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

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

Schema description coverage is 75%, with cell, remove_cell, and estimate_only already described. The description adds usage context (e.g., text-only vs asset cells) but does not significantly elaborate on parameter syntax beyond the schema. It reinforces that remove_cell is an alternative to cell, but the schema already states this. Since schema does the heavy lifting and the description adds marginal parameter-specific value, a 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 opens with a specific verb and resource: 'Add an output cell to a session that's already reached CP3.' It clearly distinguishes from sibling tools like niche_render_image_card and niche_render_reel by stating when to use and what the response's next_step directs to. It also differentiates text-only vs asset cells, making the tool's scope and behavior unambiguous.

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

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

The description provides explicit when-to-use context: 'Use this when the user picked a small initial cell set, previewed the drafts, and now wants another surface.' It also names alternatives (niche_render_image_card, niche_render_reel) and explains the removal path via remove_cell. This is a clear usage guideline that distinguishes this tool from 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?

The description goes well beyond annotations: it discloses asynchronous behavior (status=cp2_generating, poll niche_session_state), brand-fit scoring logic, the fallback recommendation_basis='default_ordering' when no brand profile is bound, and per-session caps/metering. 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?

Despite its length, the description is well-organized into sections (main behavior, custom framing, regenerate) with bolded key terms. Each sentence contributes operational detail—no fluff—and critical info is front-loaded.

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

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

The description fully specifies return shape (five angles[] with fields, angle_recommendation, status), the async poll pattern, and edge cases (no brand profile, capped sessions). With no output schema, it takes on the burden and succeeds; an agent can invoke and interpret results correctly.

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

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

Schema coverage is 80% (4/5 params documented). The description adds extra meaning beyond schema, e.g., lens is 'read on a regenerate run, and as a fallback steer for custom_framing', and custom_framing 'drafts that angle on the real story... instead of returning the proposed five'. Only session_id remains undocumented, but its purpose is self-evident.

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+resource: 'pick a story from the discovery slate and surface the strongest angles worth publishing'. It also explicitly differentiates from sibling tool niche_draft_direct by explaining when to use custom_framing instead, thus distinguishing from alternatives.

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 guidance: 'Use this instead of niche_draft_direct when you have a researched story in hand; draft_direct works from your take alone'. It also establishes clear preconditions for custom_framing and regenerate (story locked, angles ready), and explains the async polling workflow.

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?

Despite annotations being minimal (all false), the description adds rich behavioral context: it is free with no image-generation spend, undo-able with prior image preserved, publishes with caption, warns via dimension_note, and details the HTTP upload path avoiding base64 round-trip. No annotation 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?

The description is long but well-organized with numbered input modes and bolded labels. It is front-loaded with the core purpose. However, there is some redundancy with the schema's image_chunk details, making it slightly more verbose than necessary, though each section 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 complex tool with four input modes, the description covers all input paths, prerequisites, output behavior (sets post image, publishes), cost, undo capability, and performance trade-offs. Since there is no output schema, it compensates by explaining the result clearly. It is exceptionally complete.

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

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

Schema coverage is high (83%), but the description adds substantial meaning beyond the schema: it explains the full upload_ref workflow (POST to /asset/upload with bearer token), chunk size and sha256 integrity mechanics, and clarifies the 'one of upload_ref/image_url/image/image_chunk' requirement not enforced by the schema.

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

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

The description clearly states the tool's function: 'Upload or attach a user-supplied or externally-designed image... to a post.' It distinguishes from sibling tools by explicitly contrasting with niche_render_image_card (AI-generated image) and flat brand cards, 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?

Provides explicit when-to-use guidance and alternatives: names niche_render_image_card as the alternative for AI-generated images, gives a prioritized input-mode order (upload_ref, image_url, image, image_chunk) with conditions for each (e.g., 'agent can run a shell'), and notes prerequisite 'use niche_add_output first.'

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

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

Beyond the annotations (readOnlyHint true), the description reveals the tool returns a full chain in one call, includes per-question metadata (intent, prompt_hint, applies_to_field, is_already_set), and computes state based on the user's current BrandKit/BrandProfile. It also clarifies the optional brand_id reads profile state, giving a complete behavioral picture.

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 well-structured with tiers and per-question details, every sentence adds necessary context about how to use the chain. Front-loaded with the main purpose and then use cases, making it easy to scan.

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

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

Given no output schema, the description thoroughly explains the return structure (intent, prompt_hint, applies_to_field, is_already_set) and the agent's possible actions (inspect state, decide flow, ask any order, skip). It covers all necessary context for correct tool 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 input schema already provides descriptions for both brand_id and include_filled, including default behavior and purpose. The main description doesn't add significant extra parameter semantics beyond what the schema covers, 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 'Return a structured question chain' and identifies the resource (setup for BrandKit, VoiceProfile, BrandProfile). It clearly distinguishes from sibling write tools like niche_brand_kit_update by focusing on the guidance chain, not the actual update.

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 'Use this when the agent is helping a new user set up Niche and wants a predictable, brand-aware Q&A sequence instead of improvising.' It further describes tiered scenarios and notes the agent can skip or reorder questions, providing clear contextual guidance versus 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?

The description reveals crucial behavioral traits beyond the annotations: additive by default, idempotent re-runs, the overwrite rule, async background execution with fast initial response, polling expectations, duplicate attachment to in-flight jobs, voice primitives from URL text, and the possibility of visual fields landing before the voice pass. This is far richer than the annotations alone and directly guides agent expectations.

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 average, but every sentence serves a distinct purpose: purpose, overwrite safety, usage context, async protocol, duplicate handling, and edge-case completion. It is front-loaded with the primary action and then logically organized into safety, usage, and async flow. It could be slightly trimmed, but for a complex, stateful, async tool the density is justified.

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 (multiple input types, async behavior, overwrite rules, no output schema), the description covers everything an agent needs: what the return value looks like immediately ({ingest_id, status}), how to poll via the status sibling, what the final response contains (populated BrandKit, ingest report with detected/skipped/errors, diff[]), and even niche completion actions like pasting text via text= if the voice pass fails. This is outstanding completeness.

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

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

Schema description coverage is 100%, so the base is 3. The description adds meaningful context beyond the schema: text is ambiguous (URL vs paste) but URL takes precedence when both look URL-shaped; files are classified by image content and routed to slots; replace defaults to false and must only be true after confirmation; brand_id is for targeting/creating separate brand kits with a slug; brand_name is for display when creating new slots. This adds behavioral nuance not present in 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 opens with a specific verb+resource: 'Auto-populate the user's BrandKit' and enumerates the exact fields (palette, fonts, tagline, etc.). It also clearly identifies the input sources (files, URL, pasted text) and distinguishes this from sibling tools like niche_brand_kit_ingest_status by stating that this call initiates ingestion while the status tool polls for results.

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 context is provided: 'Use when the agent has brand assets in scope...' and the tool is placed as the agent-side equivalent of the web app's ingest surface. The description gives clear when-not-to-use guidance via the overwrite rule, instructing to ask the user first, prefer creating a new brand_id rather than clobbering, and only set replace=true after explicit confirmation. It even names the polling sibling and compares the pattern to niche_signal_scan/niche_session_state.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses key behavioral traits: the marker expires after 30 minutes, 'failed' means the kit was not written and gives failed_step, and 'done' includes specific arrays (detected/skipped/errors/diff/left_unchanged). This adds significant operational context not available in the annotations alone.

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

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

The description is two sentences, front-loaded with the core purpose, and uses a compact pipe-separated list for status details. Every sentence adds necessary information with no redundancies 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?

Given the absence of an output schema, the description thoroughly covers return behavior: statuses, payload contents for 'done', failure details for 'failed', and the expiration timer. This is complete for an async status poll tool with a single parameter.

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

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

The only parameter `ingest_id` is fully documented in the schema with the same meaning as in the description ('The ingest_id returned by niche_brand_kit_ingest'). The description adds no additional semantic value beyond confirming this association, so the baseline of 3 applies given 100% 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 purpose with a specific verb+resource: 'Poll the result of an async niche_brand_kit_ingest.' It distinguishes itself from the sibling `niche_brand_kit_ingest` by explicitly referencing that async process as the context for this status polling tool.

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

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

It provides clear usage context: 'Pass the `ingest_id` it returned' and explains the statuses to guide the polling loop ('ingesting' keep polling, 'done' response, 'failed' kit not written). It does not explicitly discuss when not to use it or alternatives, but given the tool's specific role, the context is strong enough for a 4.

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 reveals key behaviors beyond annotations: partial-field updates ('Only fields you pass are touched'), list replacement semantics, response shape (diff[] and full updated kit), and soft-reversible archiving ('soft and reversible; no hard delete'). These details are critical for a mutation tool with destructiveHint=false, adding context annotations don't provide.

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

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

The description is lengthy but efficiently organized: purpose first, then update semantics, then archiving. Each sentence adds value, and the length is justified for a tool with 27 parameters and complex archiving behavior. It avoids redundancy and front-loads the core 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?

Despite no output schema, the description states the response includes a diff and full kit, covering the main expected return. It addresses edge cases for archiving (default brand, published history, archive_scope='test') and alternative usage flows via siblings, making it comprehensive 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?

With schema coverage at 52%, the description compensates by grouping fields (tagline, boilerplate, voice_notes, etc.) and explaining behavior patterns like list replacement and omit-preserves-current-value. It also clarifies archiving parameters and their consequences, though it doesn't enumerate every parameter individually.

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 'Set specific BrandKit fields by name', clearly identifying the write path and distinguishing it from the ingest engine and guided setup. It enumerates the structured fields, making the resource scope explicit and differentiating it from sibling tools like niche_brand_kit_ingest.

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 niche_brand_kit_ingest fills the easy stuff, or to commit values the user answered through niche_brand_kit_guided_setup.' It also provides exclusion conditions for archiving (default/active brand can't be archived, published history requires acknowledge=true), offering clear guidance over 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=true and destructiveHint=false. The description adds meaningful behavior: omit brand_id to list all summaries vs. pass it to get full profile, and it specifies the return fields (full profile JSON, schema_version, timestamps, brand_kit_sync_status). This goes beyond the structured annotations.

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

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

Two compact paragraphs: the first condenses purpose and use cases, the second covers parameter modes and return details. Every sentence earns its place; 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?

With no output schema, the description compensates by specifying the return payload and its fields. It also covers both operational modes (get vs list) and the purpose context. For a simple read-only tool, this is complete and well-rounded.

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

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

The input schema has 100% coverage with 'Omit to list all.' The description adds value by clarifying the output differences: listing returns summaries of (brand_id, updated_at), while reading one returns the full profile JSON with additional metadata. This enriches the parameter's 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 opens with 'Read back the persisted brand profile without modifying it'—a specific verb, resource, and non-mutating scope. It distinguishes itself from the sibling 'set' tool by framing a use case as 'inspect the current shape before a partial update.'

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 three explicit usage contexts: confirm a profile landed, check the active profile, or inspect before a partial update. It doesn't explicitly name alternative tools or state when not to use it, but the read-only framing and update context imply the boundary.

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 extensively discloses behavior beyond the annotations: re-setting replaces prior profile, validation uses tiered lints (error/warn/info), conflicts with brand kit are not stored, missing voice falls back to a default stub, and malformed sets return a template. This far exceeds the minimal readOnly/destructive 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 long but appropriately so for a complex tool with nested objects. It is front-loaded with the core purpose, then logically organized into required sections, validation, and brand_id semantics. Every sentence adds actionable information without 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?

With no output schema, the description compensates by disclosing the response format (lints[], conflicts[], template) and edge-case behaviors (default voice stub, brand kit precedence). It covers all necessary operational context for a complex setter 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% and the description adds substantial meaning: profile structure details (identity, voice, lexicon, framing, verifier_overrides, etc.), encoding of closed framing set behavior, error response with valid slugs, and the template return on malformed sets. brand_id format and uniqueness are also clarified.

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 'Set or update the persisted brand profile for a brand' with a clear verb and resource. It enumerates the pipeline stages the profile applies to, distinguishing it from sibling tools like niche_brand_profile_get and niche_brand_kit_update. The scope is unambiguous.

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

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

The description provides clear context for when to use the tool: 'persist a profile derived from a repo or docs so future runs inherit the rules, or to update voice rules and banned terms before the next run.' It does not explicitly name alternatives or exclusion criteria, but the usage context is well-defined.

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 give no safety hints (all false), so description carries the burden. It discloses async behavior (returns status=cp3_generating, poll session_state), trust data nested under outputs[i].trust, and the brand_choice_required refusal mode. However, 'lock the chosen angle' is vague about whether the angle is consumed/irreversible, and no mention of rate limits or cost beyond estimate_only.

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 (functionality, async/polling, trust data, brand edge case). Though long, every sentence adds operational value. A bit dense but not bloated; front-loads the core 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?

For a complex async tool with no output schema, it covers purpose, async flow, trust data specifics, and brand branching. Missing a clear description of the output object structure (beyond trust fields) and how outputs[] items are shaped, but sufficient for invocation and follow-up polling.

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 75% of parameters (angle_id, brand_id, estimate_only described). Description repeats brand_id behavior but adds little beyond schema; session_id remains undocumented, and estimate_only isn't mentioned in description. Thus no significant added meaning over 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's function: lock an angle and create platform-native drafts (LinkedIn, X thread, Instagram, newsletter/long-form). It distinguishes from sibling tools like publish/revise by emphasizing 'ready to review and publish' and 'downstream payoff once the story and angle are decided.'

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 context for when to use (after angle is decided) and describes the multi-brand workflow including stopping to ask the user and re-calling with brand_id. It doesn't explicitly name alternatives, but the workflow implies sequencing. Slightly short of 5 due to lack of explicit 'when not 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?

Adds rich behavioral context beyond annotations: the async session flow (returns session_id in under 2s, poll niche_session_state to checkpoint, then read outputs[]), the no-scan/no-picks behavior, and the brand binding effect. No contradiction with annotations.

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

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

The description is well-structured and front-loaded, with every sentence earning its place. It starts with purpose, then usage, contrast, requirements, and async behavior—all concise and 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?

For a tool with 8 parameters, no output schema, and conditional required inputs, the description covers all essential context: purpose, usage, asynchronous flow, brand binding, and reading outputs. The schema handles parameter details, so the description complements it without redundancy.

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 already covers all parameters 100%, so baseline is 3. The description adds meaningful semantic value by stating the 'at least one of take/source_url/source_text' constraint (not in schema) and clarifying that the source parameters repurpose an existing page.

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-resource pairing ('Draft the creator's own take or product straight into posts') and explicitly contrasts with the signal pipeline ('this is for write this exact thing'), clearly distinguishing it from sibling tools like niche_signal_scan. The title 'Draft directly (no scan, BYOC)' reinforces 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?

Explicitly states when to use this tool ('product-led or bring-your-own-content work'), gives concrete examples, and names the alternative pipeline (niche_signal_scan) with a clear when-not-to-use boundary. Also provides operational 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?

Annotations already indicate destructiveHint and readOnlyHint=false, but the description goes far beyond by explaining that commit is irreversible, defaults to dry_run=true, requires idempotency_key for commit, verifier blocks prevent publishing, and not_connected returns a connect_url. Also covers scheduling and cancellation behavior. No contradiction with annotations.

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

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

The description is fairly long but well-structured with paragraphs separating safety, scheduling, and platform selection. Every sentence contributes critical operational detail, though a slightly tighter edit could improve scannability. It is not wastefully verbose.

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

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

Without an output schema, the description compensates by explaining response states (status='not_connected', 'ambiguous_platform', 'scheduled', resolved_cell, publish_cost, next_step). It covers edge cases, scheduling, dry-run behavior, and human-in-the-loop requirements, making it nearly complete for a complex publish 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 covers 75% of parameters with descriptions. The tool description adds valuable context beyond the schema, such as preferring exact cell strings over family names, the meaning of status='ambiguous_platform', and the idempotency guarantee. This enriches understanding but some parameters like session_id are minimally described.

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 'Publish a single output to its platform,' a clear verb+resource statement. It immediately distinguishes itself from sibling draft/rendering tools by focusing on the publish action and its dry-run/commit flow.

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

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

Provides clear context on when to use the tool (final publish step) and when to use dry-run vs commit. Does not explicitly name alternative sibling tools for other scenarios, but the guidance around previews and explicit human go-ahead is strong. Lacks explicit 'rather than using X' statements.

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?

Without relying on annotations (readOnlyHint=false, destructiveHint=false), the description discloses no-op behavior, server-side sanitization, error conditions for out-of-bounds indices and non-carousel slide_patches, and the response's diff[] array. It also reveals the consequence of angle/story changes invalidating the verifier trust block, which annotations do not capture.

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?

Despite being a dense paragraph, every clause adds behavioral detail and no sentence is redundant. The description is appropriately scaled to the tool's 7-parameter complexity, front-loading the purpose and then layering edge cases.

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 provides a thorough operational picture: accepted fields, no-op/change behaviors, angle-change routing, response diff, platform-specific constraints, and sanitization rules. With no output schema, it still informs agents what the response contains, making the tool highly navigable.

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 86%, so the schema already explains most parameters. The description adds unique context by mentioning card_headline (rewords image card header) and clarifying caption as a legacy alias for script.body/script.caption, but largely reiterates schema descriptions for other fields.

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

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

The description opens with 'Applies the values you pass to a specific output,' immediately establishing the tool's role as a revision/edit operation on an existing draft. It enumerates editable fields (caption, hashtags, script updates, carousel slides) and contrasts with niche_angle_propose for angle/story changes, distinguishing it 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?

It explicitly states when not to use the tool: 'Angle and story changes still go back through niche_angle_propose' and warns that passing no editable field returns status:'no_change'. It also specifies platform-specific usage, e.g., slide_patches is for linkedin_carousel only, and directs agents to apply_hook_variant_index for cheap hook splicing.

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 provide readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the description carries the full burden of explaining side effects and lifecycle. It adds rich behavioral detail: non-blocking session_id return, polling cadence, cp1_awaiting_story status, synthesis timing with a hard cap, and the synthesis:'none' branch. This goes far beyond the structured annotations and contains no contradiction.

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

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

The description is long but well-structured into purpose, async workflow, and brand handling. The opening sentence front-loads the core purpose, and each subsequent paragraph addresses a distinct aspect (polling, synthesis, brand binding, handoff to niche_angle_propose). Every sentence earns its place for this complex tool, though the web-app equivalence sentence could be trimmed without losing essential guidance.

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

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

With no output schema, the description must explain return values and state transitions, and it does so explicitly: session_id, cp1_awaiting_story, stories[], synthesis[], synthesis_shortfall_note, brand_choice_required, and brand_options are all named. It covers the entire lifecycle from submission through polling to handing off to niche_angle_propose. The only minor omission is error/rate-limit behavior, which is not critical given the detailed workflow guidance.

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

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

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds brand_id semantics not fully captured in the schema: omitting brand_id auto-binds a single/default brand, multi-brand accounts return brand_choice_required with brand_options, and 'none' is a valid unbranded value. It also clarifies the behavioral effect of synthesis:'none', adding value 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 opens with a specific verb+resource: 'research and analysis: answer an analyst-shaped question over fresh-scanned sources and get an intelligence answer as the deliverable, not a single post.' It lists concrete use cases and explicitly contrasts with single-post tools, distinguishing it from siblings like niche_angle_propose and niche_draft_create. The 'same engine as the Niche web app' note further clarifies its scope.

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

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

The description explicitly says 'Use for:' and gives four analyst-style example questions, making the intended context unmistakable. It also tells the agent what not to do ('do not synthesize your own narratives over the slate, present these') and describes the follow-up path to niche_angle_propose. This is strong when/when-not guidance, even though it doesn't name an alternative for the initial query.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is known. The description adds significant nuance: return ordering, the distinction between `outcome` and `status`, and that a `failed` status is usually a walk-away not an error. It also details what `recent_outputs` contains. 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?

The description is two tight paragraphs. First states action, return fields, use case, and ordering. Second explains the crucial outcome/status distinction. Every sentence carries information, no filler.

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

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

With no output schema, the description compensates by listing exact return fields and the structure of `recent_outputs`. It also explains sorting and outcome semantics. Fully covers the tool's role among many siblings and all relevant aspects.

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 semantic value by clarifying that `status_filter` matches raw status not the derived `outcome`, and by explaining the purpose of `include_outputs` for locating past assets. These clarifications are not in 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 opens with a specific verb+resource: 'Enumerate the user's recent sessions.' It clearly lists the return fields and explicitly states when to use it (when session_id lost or to find an in-flight session), distinguishing it from sibling tools that mutate sessions (e.g., niche_session_cancel).

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 'Use this when the session_id has been lost... or to find an in-flight session to resume' and explains the `include_outputs` use case ('Use it to locate a past asset'). However, it does not mention alternatives or exclusion criteria; sibling tools like niche_session_state are not referenced. Clear context without exclusions/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 only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description goes far beyond this by disclosing credit costs, async vs synchronous behavior, idempotency ('A repeat call while a render is in flight is a no-op'), the fact that 'restore' reverts from history, and named error cases (render_not_ready, render_not_configured, render_card_unavailable). All of this is useful and non-contradictory 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 long but well-structured with scopes and backgrounds broken out. The first sentence front-loads the core purpose, and subsequent bullets are scannable. Some redundancy exists with the schema (e.g., background options are repeated nearly verbatim), but the complexity of the tool justifies the length. Not maximally concise, but certainly not bloated.

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 16 parameters and no output schema, the description is remarkably complete. It covers asynchronous status ('returns status='rendering_image_card''), polling flow via niche_session_state, credit costs, sync vs async modes, idempotency, error conditions, and the zero-cost scopes (recomposite, restore, reframe, brand_color, svg). The agent has enough context to select and invoke the tool correctly in most situations.

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%, and every parameter in the schema already carries a detailed description (including credits, timing, defaults, and the 'ignored otherwise' clarifications). The top-level description largely repeats this information rather than adding new semantic layers. Since the schema does the heavy lifting, a 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 opens with a specific verb and resource: 'Render a visual onto a post at CP3, or edit an existing image.' It clearly distinguishes this tool from siblings like niche_render_reel (video) and niche_attach_image (attaching existing assets) by scoping it to image cards on a post at CP3.

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 excellent in-tool guidance: 'recomposite' for wording iteration, 'svg' as 'the right choice for data, labels, charts', and the note that SVG is the only visual that works from a network-locked sandbox. It also explains when to poll and what error conditions mean. However, it does not explicitly compare to sibling tools like niche_render_reel or niche_reuse_asset, so the agent must infer those boundaries from titles alone.

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

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

Despite annotations only providing readOnlyHint=false and destructiveHint=false, the description discloses idempotency ('a prior render is replaced'), per-scope charges, error codes (503/400/422), and nuanced behaviors such as caption_sync_mode being ignored when captions are disabled and music being unchangeable on re-render. 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?

Description is structured into overview, scope, options, and error/cost sentences and front-loads the main deliverable. The options paragraph is a dense run-on but condenses 20 parameters usefully; minor redundancy with schema and one default-value error keep it just below excellent.

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 20-parameter tool with no output schema, the description covers scope semantics, cost, errors, and edge cases like retained footage requirements. It lacks explicit detail on return/download mechanics beyond 'downloadable file' and does not explain how the agent should poll or locate the result, so it is complete but not fully.

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

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

Schema coverage is 100%, so baseline is 3, but the description prose adds cross-parameter semantics such as length vs target_duration_sec, music_direction implicitly enabling music, cell only affecting bookkeeping, and endcard_color re-resolving text. However, the prose states caption_sync_mode defaults to 'phrase' while the schema says default is 'beat', a misleading inconsistency preventing a 5.

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

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

Description opens with specific verb 'Render' and resource '9:16 vertical reel for a session at CP3', detailing compositing of stills, voiceover, motion, captions, and endcard. This clearly distinguishes the tool from sibling niche_render_image_card and conveys the exact deliverable.

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 gives clear context requiring a session at CP3 and explains scope variants ('full', 'recomposite', 'endcard', 'beat:N') with when each is appropriate. It does not explicitly name alternatives relative to sibling tools, but the CP3 prerequisite and scope handling provide actionable usage guidance.

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

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

The description discloses behavior beyond the annotations: it copies static_urls, is instant/free/no credits, idempotent, and requires a rendered source. Since readOnlyHint=false aligns with the mutation action, there is no contradiction. The added detail fully informs the agent of operational side effects.

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

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

The description is compact and well-structured: first sentence states the core action and benefit, second provides usage context with a counterexample, and third covers prerequisites and idempotency. No redundant phrases; 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 moderate complexity, the description fully covers what it does, when to use it, prerequisites, behavioral effects, and idempotency. The absence of an output schema is acceptable because the purpose is a simple copy operation and the outcome is implied by the description.

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

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

Schema covers 67% of parameters with examples (from_cell and to_cell). The description adds the mechanism 'Copies the source's static_urls onto the target', which explains the relationship between parameters and the effect. session_id is left to inference but is a common field; the description partially compensates for the gap.

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

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

The description opens with a specific verb and resource: 'Copy an image that already exists on one output onto another cell.' It immediately clarifies the operation's purpose and distinguishes it from niche_render_image_card by contrasting cost and outcome, making the tool's intent 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?

Explicit usage guidance is provided: 'Use this when the user wants "the same image" on a second surface... instead of niche_render_image_card.' It also states prerequisite conditions (both cells must exist, source must have rendered image) and points to niche_add_output as a fallback, offering both when-to-use and when-not-to-use context.

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

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

Beyond the annotations (destructiveHint=true), the description discloses key behaviors: status changes to failed, error_message default, idempotency, and detailed credit handling. It also clarifies what is NOT affected (history and audit trail preserved), which is useful context for a potentially destructive operation.

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

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

The description is well-structured into clear paragraphs, each addressing a distinct aspect: action, use case, idempotency, and credits. Every sentence adds value, with no fluff or repetition. It is slightly longer but appropriately so for a tool with complex side effects.

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 cancellation tool with no output schema, the description thoroughly covers behavior, side effects, idempotency, and credit implications. It also addresses the destructive nature and provides guidance on when to use an alternative. This is complete enough for an agent to confidently invoke the tool.

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

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

Schema coverage is 50% (reason has a description, session_id does not). The description adds context that the reason becomes the error_message and that a default 'cancelled by user' is used when omitted. It does not detail session_id further, but the purpose is clear. The description compensates reasonably for the schema gap.

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

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

The description clearly states the tool cancels a running session, marking it as failed with an error_message and stopping the orchestrator. This distinguishes it from related sibling tools like niche_session_revert and niche_session_state, and it also contrasts with the REST DELETE endpoint for hard cleanup.

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 this tool: to free a slot under the concurrent-session cap without deleting the session. It also provides an alternative: use the REST DELETE endpoint for hard archive cleanup that wipes outputs. This gives clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds details about output formats (markdown vs. json), what each contains, and that it preserves session_id/story_id traceability, providing value beyond the annotations.

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

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

The description is detailed but well-structured: opening purpose, usage guidance, two bullet-point formats, and a traceability paragraph. Every sentence earns its place, though the format bullets are somewhat verbose. Still within reason for a tool with complex output shapes.

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

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

With no output schema, the description thoroughly explains what the tool returns (content of markdown and json exports, traceability, and workflow fit). It also covers when to use it, making the description near-complete for an export tool with only two 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 covers format with enum/default but not session_id. The description adds substantial detail about both formats (markdown human-readable vs. json machine-shaped) and the artifact's content, compensating for the 50% schema coverage. It doesn't elaborate on session_id, but that is self-explanatory.

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 'Export a session as a structured calendar artifact' with a specific verb, resource, and output type. It distinguishes from siblings like niche_list_sessions and niche_signal_scan by emphasizing the structured backlog artifact and workflow integration.

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 says 'Use after a niche_signal_scan when you want a metadata-rich content backlog instead of running individual pieces end-to-end.' This gives clear when-to-use context and an implicit alternative, making it easy for an agent to choose correctly.

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 far beyond the destructiveHint annotation by detailing idempotency, state transitions (CP1/CP2), cleared fields, the confirm_discard flow, and the financial consequence of discarding paid-for drafts. This richly discloses behavior not otherwise visible.

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-organized and front-loaded with the purpose. Each paragraph adds unique value: usage context, parameter behavior, idempotency, and safety. No fluff or repetition; 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 complex destructive tool with no output schema, the description covers all essential aspects: what triggers use, exact state changes, idempotent behavior, the confirmation safety mechanism, and credit implications. It leaves no critical gaps for an agent to safely invoke it.

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

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

Schema coverage is only 33% (only acknowledge_discard has a description). The description compensates by explaining the 'to' parameter's two values (story/angle) and their distinct effects, plus clarifies acknowledge_discard's necessity and consequence. session_id is self-evident.

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 reverts a session to an earlier checkpoint, with specific verbs and resources. It distinguishes itself from siblings like niche_session_cancel by focusing on checkpoint reversion without starting a new scan, and elaborates on the two target checkpoints (story/angle).

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 picked story/angle isn't right and you want to re-pick 'without starting a new scan.' It also covers exclusions and caution around reverting finished runs, providing clear context for safe 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?

Discloses numerous behavioral traits beyond the readOnly/destructive annotations: sleep-and-wake polling semantics, sparse response behavior, outcome vs. raw status nuance ('a failed status is usually an expired walk-away'), alias behavior, and rate-limit risk (HTTP 429). Annotations already mark readOnlyHint=true and destructiveHint=false, so the description adds rich context rather than repeating safe-read facts.

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 exceptionally dense and well-organized: front-loaded purpose, then return fields, then polling guidance, then sparsity and edge cases. Each section earns its keep; there is no filler or repetition. It could arguably be tightened, but the structured paragraphs and clear topical separation make it easy to scan despite 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 the tool's complexity (8 params, 17-status state machine, no output schema), the description covers everything an agent needs: response fields, trust data location, status_glossary, outcome semantics, aliases, rate limits, sparse mode, and recommended loop. It fully compensates for the missing output schema and leaves no obvious gap.

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

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

Input schema already covers all 8 parameters with full descriptions, defaults, and enums (100% coverage). The description elevates this by explaining how parameters interact operationally—e.g., wait_until='checkpoint' vs 'change', wait_for alias precedence, include_unpicked sparsity semantics, and recommended concrete values (wait=30). The baseline for 100% coverage is 3, but the added operational context justifies 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 opens with 'Universal poll endpoint: read the full current state of a session' and enumerates exact return fields (status, ranked stories, picked IDs, draft outputs, trust fields, elicitation hint). This specific verb+resource scope clearly distinguishes it from siblings like niche_signal_scan (kickoff) and niche_list_sessions (session list).

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

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

Provides explicit when-to-use and how-to-use guidance: 'Call this whenever you need to check progress; it's safe and cheap' and recommends a polling loop with wait=30 and wait_until='checkpoint'. It also warns against rapid polling ('Avoid polling every few seconds without wait, which may be rate-limited') and explains when to use wait_until='render' or 'synthesis' for sibling render/query tools, effectively defining 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?

The description discloses substantial behavioral traits beyond the annotations: it starts a run, may hold a reservation, can bill, supports idempotency, auto-dedupes identical scans, and can block up to ~45s in fast mode. It also notes the effective profile is snapshotted at scan time. This far exceeds the minimal annotation set and gives the agent critical operational expectations.

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 dense; every sentence provides actionable guidance. It is front-loaded with the core purpose, then return semantics, then brand profile nuances. While it could be trimmed slightly, the complexity of the tool justifies most of the length, and there is no filler or 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?

The description covers the return value (session_id plus initial status), how to retrieve results (poll niche_session_state), cost estimation via estimate_only, and idempotency. With no output schema, it explains what the agent needs to know to proceed. It doesn't describe the slate's internal structure, but this is not strictly necessary for successful invocation and polling.

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 100% coverage with detailed parameter descriptions, so the baseline is 3. The description adds extra semantics beyond the schema, especially around brand_id: multi-brand behavior, brand_choice_required, brand_id:'none' for unbranded runs, and the deep-merge of profile_overrides. It also adds context for idempotency and retry behavior, supplementing the schema's parameter docs.

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+resource: 'Niche story discovery: find stories worth writing about, then draft and publish platform-native social content.' It explicitly distinguishes itself from content generation: 'This is story discovery, not content generation,' and describes the output as a 'ranked story slate with provenance.' This clearly separates it from sibling draft/publishing 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 context for when to use the tool ('the editorial-intelligence step before any writing') and when to poll via niche_session_state. It also provides exclusions such as 'You do NOT need niche_whoami to brand a run.' However, it doesn't explicitly name alternative sibling tools for when not to use this tool, but the 'when' and 'when-not' guidance is strongly implied.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that this is a persist operation, explains the no-op default behavior ('first run wins, subsequent runs are no-ops'), describes server-side scraping for URLs, and notes the return of a diff of changes. This adds substantial behavioral context and does not contradict any annotation.

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

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

The description is organized into three focused paragraphs: purpose, input shapes, and return value. It is front-loaded with the main action, and every sentence contributes meaningful information without 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?

Given 5 parameters, useful annotations, and no output schema, the description covers the core purpose, both input modes, precedence, content quality, side effects (overwrite behavior), and return value. It provides enough context for an agent 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 detailed parameter descriptions, so the baseline is 3. The description adds value by explicitly stating the posts-vs-url precedence rule and explaining the brand-scoped behavior, which is not fully apparent from individual parameter 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 'Extract voice primitives ... and persist onto the user's VoiceProfile,' identifying the specific verb, resource, and outcome. It distinguishes the tool from siblings like niche_brand_profile_get/set by focusing on voice ingestion from post-shaped text, and it explains the purpose ('thread into content generation').

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 on input shapes: pass `posts` or `url`, with precedence ('Inline posts win when both are given'). Also gives quality requirements ('≥80 chars each', 'user's own writing, not press articles or marketing copy'). However, it does not directly contrast with sibling tools such as niche_brand_profile_set, so explicit alternatives are not named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'read-only call.' It adds valuable context beyond annotations by detailing what the tool returns: registered tool names, live tool count, account plan/credit balance, capability map, and brand state. This helps the agent predict the output and plan actions, though it does not describe internal mechanics or edge cases.

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

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

The description is three sentences long and front-loaded with the core purpose. It lists the main return categories in a compact, scannable style, and every sentence adds value—no filler, no redundancy. The structure effectively conveys both behavior and usage in minimal space.

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 is complete for a tool with no output schema: it covers the full set of return values (catalog, account, capability map, brand state), the intended usage ('Call it first'), and the safety profile (read-only call). It even hints at the recommended flow within the capability map. The optional parameters that alter output are already detailed in the schema, so the description does not need to repeat them.

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%, with all three optional boolean parameters clearly documented in the input schema (include_test, include_all_brands, include_brand_assets) including their defaults and effects. The description does not add extra parameter semantics beyond what the schema provides, but this is acceptable because the schema already carries the full burden. 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 the tool's function: 'List the full tool catalog and orient the agent, in one read-only call.' It enumerates the exact resources returned (tool catalog, account info, capability map, brand state) and distinguishes itself from sibling action tools like niche_draft_create or niche_render_image_card by serving as an orientation/meta tool. The phrase 'Call it first' reinforces its unique role.

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: 'Call it first to discover what's available, plan a session, and check credits before spending.' This tells the agent exactly when to invoke it and why, while also implying it should precede other tool calls. It does not explicitly mention exclusions, but given its read-only and orientation purpose, the guidance is sufficient and clear.

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