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

The description discloses important side effects beyond the annotations: 'CREATES the collection if the name is new' and 'Pass an empty collection name to ungroup'. It also adds a CAPABILITY note about draft safety, which is not present in the annotations (readOnlyHint=false only indicates a write operation). This adds meaningful context, though it doesn't fully specify the effect of ungrouping on the collection itself.

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 appropriately sized and front-loaded with the core purpose. Each sentence adds unique information: side effects, downstream usage via schedule_post, parameter guidance, ungroup behavior, and capability context. 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?

Despite having no output schema, this simple two-parameter tool is fully described. The description covers prerequisites (list_integrations), side effects, usage patterns, and safety/capability notes, making it complete 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?

The schema already provides 100% coverage with descriptions for both 'accountId' and 'collection'. The description adds value by specifying that 'accountId' is from list_integrations and reiterating the ungroup behavior for an empty collection name, slightly enriching the schema's baseline meaning.

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 action: 'Group a connected account into a collection' and elaborates that it also creates a collection if the name is new. It differentiates from siblings by explaining the relationship to schedule_post via the 'collection' field, making the tool's role distinct.

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: to group accounts, create a collection, or ungroup via empty collection name. It also references list_integrations for the accountId, implying a prerequisite. However, it doesn't explicitly state when not to use it or name alternative grouping tools, so it stops short of a 5.

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

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

The description adds significant behavioral context beyond annotations: it warns of reaching a live audience, explains schedule_hint resolution logic, notes 403 for draft-scoped tokens, and describes thread behavior for multi-segment drafts. 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 dense but well-structured, front-loading the critical human gate warning. Each sentence provides essential information without wordiness.

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 safety, usage conditions, scheduling behavior, and token constraints thoroughly. The only gap is the lack of return value description, but given the mutation nature and no output schema, this is not a critical omission.

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

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

The description explains that segments are optional replacement segments and scheduled_for is an explicit future override, adding meaning beyond the bare schema. While draft_id is not elaborated, it's self-evident. It compensates for the low 33% schema description 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: approving a pending draft and scheduling the real post in one step. It distinguishes from siblings by highlighting the human gate, the combination of approval+scheduling, and the special handling of multi-segment Twitter drafts as threads.

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: only after human operator has reviewed and approved. Explicitly forbids autonomous approval. It also notes the alternative path (human must approve at timetopost.co for draft-scoped tokens) and provides context about the publish capability affecting live audience.

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 minimal (no hints), but the description extensively discloses behavior: it never overwrites existing settings, preserves user-typed pillars, enforces approvalMode 'draft', never opts into unattended publishing, affects monthly quota, and returns a specific structure. It also states the CAPABILITY 'draft' and safety for draft-only agent tokens, adding important context beyond the schema.

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

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

The description is long and somewhat run-on, but every sentence conveys useful information for a complex tool. It is front-loaded with the main purpose and clearly organized via parentheticals. Slightly verbose but justified by 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 no output schema, the description explains the return value in detail (config, proposedTopics, firstPost). It covers preconditions (connected site), side effects (quota, approval), and safety/limits. For a 2-param tool, this is highly 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 both parameters with descriptions (100% coverage), so baseline is 3. The description adds nuance: generateFirst queues a draft behind human approval and uses quota; omitting it configures without generating. It also clarifies siteId source. This adds marginal meaning 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 tool's function: one-click AutoSEO onboarding that combines topic proposal and configuration. It explicitly contrasts with the manual sequence (autoseo_propose_topics → autoseo_configure) and names sibling tools, making its purpose and scope 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?

Explicit usage guidance is provided: 'Prefer this right after autoseo_connect_site when the user just wants it set up; use autoseo_propose_topics + autoseo_configure instead when they want to hand-pick topics.' This clearly states when to use and when not, naming the alternative.

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

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

With annotations only providing false hints (readOnly, destructive, etc.), the description must and does carry the behavioral burden. It explains that approvalMode 'draft' routes to the pending-approval queue, 'auto' publishes unattended only with explicit opt-in, socialRepurpose never auto-posts and is off by default, and publicBaseUrl affects git_pr connector behavior. It also includes the CAPABILITY note that this creates content that cannot reach an audience on its own, adding safety information 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 appropriately sized for a tool with 9 parameters. It front-loads the main purpose in the first sentence, then gives targeted detail for the most complex parameters (approvalMode, socialRepurpose, publicBaseUrl), and ends with sequencing. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (9 params, nested objects, no output schema), the description covers side effects, prerequisites, and safety. However, it does not describe the expected return value or confirmation behavior after a successful call, which would help an agent in a workflow with no output schema. Still, the behavioral and sequencing coverage is strong.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it clarifies that approvalMode 'draft' is recommended/default, socialRepurpose is off by default with never auto-post guarantee, and publicBaseUrl only matters for git_pr connector. This is decision-guiding and adds value, but some nuance (like platform defaults) is already in the schema, so a 4 is appropriate.

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

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

The description clearly states the verb 'Set' and the resource 'the standing AutoSEO configuration for a connected site', enumerating all configuration areas (topics, cadence, backlinks, image style, approval mode, social repurpose). It distinguishes itself from sibling tools by naming the configuration scope and its sequencing role with autoseo_verify_site and autoseo_propose_topics.

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 sequencing guidance: 'Call this after autoseo_verify_site confirms the site is live, and ideally after autoseo_propose_topics...' It also warns about approvalMode 'auto' requiring explicit user opt-in. However, it does not explicitly mention alternatives like autoseo_auto_configure or state when not to use this tool, so it stops short of full when/when-not coverage.

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 many behavioral traits beyond annotations: for wp_rest, 'connect runs the REAL capability probe, so a bad credential fails right here with the exact reason'; for git_pr, 'connect verifies write access and auto-detects the SSG + content convention'; and for webhook, the signing secret generation. It also notes the CAPABILITY: 'draft' and the safety implication. This is extensive and transparent.

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

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

The description is long but well-structured with logical sections: start, return, each connector kind, post-connect steps, and capability warning. It is dense and front-loaded with 'START HERE'. However, it is somewhat verbose; while every sentence carries meaning, the length could be slightly trimmed without losing information.

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

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

Given the tool's complexity (4 connector kinds, 12 params, no output schema), the description is remarkably complete. It explains the return value ({ id, kind, publicToken, capabilities }), side effects (e.g., probe for wp_rest, write-access verification for git_pr), and the overall workflow. It also covers edge cases like publicToken usage and capability restrictions. This is fully sufficient for an agent to 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?

Despite 100% schema coverage, the description adds meaningful semantics by grouping parameters per kind and explaining defaults and requirements. For example, 'kind "hosted" is the ZERO-SETUP DEFAULT — needs ONLY name', and 'mode ... "pr" opens a reviewable pull request per article, the default'. It clarifies the exact meaning and combinations of parameters, going well 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's purpose: 'Connects ONE of the four connector kinds' and 'START HERE for AutoSEO on a new site.' It names the specific resource (site) and action (connect), and distinguishes itself from sibling tools by positioning as the entry point. The return object is also specified, making the tool's role 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 explicitly states when to use this tool ('START HERE') and provides guidance for choosing among the four connector kinds, e.g., 'pick it when unsure' for hosted. It also directs follow-up steps: 'After ANY kind: autoseo_configure → autoseo_propose_topics / autoseo_generate_post.' This is a clear usage roadmap with 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: it never auto-publishes, runs dedup/uniqueness/quality gates, includes jsonldValid in the response, and is 'Safe for a draft-only agent token.' This adds substantial context about side effects and safety that annotations alone do not convey.

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

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

Though longer than average, every sentence earns its place: core purpose, scheduling behavior, quality gates, response signal, style rules, and safety. The description is front-loaded with the primary function and then logically expands into operational constraints, so it is structured and efficient for its 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?

The description covers generation behavior, safety (never auto-publishes), quality gates, a return-value signal (jsonldValid), and detailed writing style policies. Even without an output schema, an agent has enough contextual information to invoke the tool correctly and avoid common pitfalls (em-dashes, hashtag spam, AI-sounding tone).

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 the baseline is 3, but the description adds meaningful semantic detail: 'schedule is an optional future ISO datetime; omit it to leave the post as an unscheduled draft' and reinforces topic sourcing from autoseo_propose_topics. This goes beyond raw schema definitions without fully needing to, hence a 4.

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

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

The description clearly states the tool 'Generate one AI-drafted, answer-shaped blog post... land it as a draft awaiting approval (or a future schedule)' and explicitly says 'this never auto-publishes on its own,' distinguishing it from publish_post or schedule_post siblings. The verb+resource+outcome is 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?

The description provides explicit when-to-use guidance: 'Source topic from autoseo_propose_topics rather than guessing one' and 'Before drafting, read the account's recent posts with list_posts and match their voice.' It also clarifies the schedule optionality and the draft-only safety, giving clear context 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?

Annotations already declare readOnlyHint=true and idempotentHint=true; the description reinforces this with 'CAPABILITY: read — side-effect-free'. Beyond that, it discloses behavioral details not in annotations: what the returned kit contains, the conditional 'not needed for wp_rest' behavior, and the live-vs-rebuild implications of each renderMode, giving agents a clear picture of the tool's effects and limitations.

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

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

The description is front-loaded with the main purpose and each subsequent sentence earns its place, but it is a dense single paragraph with multiple clauses that could be structured more cleanly. The final 'CAPABILITY' line is redundant with annotations, adding a minor inefficiency without affecting 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?

With no output schema, the description fully covers what the tool returns and what the agent should do with it (read files, adapt, write, tell user to deploy). It addresses parameter choices, deployment prerequisites, exclusions, and follow-up steps, making it complete enough for correct invocation in nearly any scenario.

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%, but the description adds substantial decision-making value: it explains the 'kind' default and when not to use it, elaborates on each renderMode's meaning and trade-offs (default/recommended, fastest, legacy), and clarifies when to pass 'stack' and what happens if omitted. This goes far beyond the raw 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 uses a specific verb ('Fetch') and identifies the resource ('AutoSEO integration kit') while detailing its contents (endpoint contract, code templates, install instructions). It further distinguishes itself from siblings by explicitly framing it as the follow-up to autoseo_connect_site and not needed for wp_rest sites, making its 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?

The description offers explicit usage context: 'Call this right after autoseo_connect_site with kind "webhook"' and 'Not needed for kind "wp_rest" sites'. It also provides conditional guidance for 'stack' (omit for generic contract) and clear recommendations among renderMode options, plus a follow-up pointer to autoseo_verify_site, fully covering when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds 'CAPABILITY: read — side-effect-free' and specifies that the output includes connection health, which is useful beyond the annotations. 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?

Two sentences with clear front-loading of purpose and usage. The additional capability note is brief and does not waste space. Every sentence contributes 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?

For a list tool with no output schema, the description sufficiently explains return fields, scope (active org), and use cases. 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?

The tool has zero parameters and schema description coverage is 100% (trivially). Baseline for 0 params is 4. The description doesn't need to explain parameters; it focuses on return contents, which is appropriate.

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

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

The description clearly states the tool lists connected AutoSEO sites/targets for the active org, with specific fields (id, kind, name, capabilities, connection health). It distinguishes from sibling tools like autoseo_connect_site and autoseo_verify_site by the action 'list' and the resource 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?

Explicitly says when to use it: to find a siteId for autoseo_configure, autoseo_propose_topics, or autoseo_generate_post, or to check a site's status before troubleshooting a failed publish. This provides clear context and implies alternatives by naming downstream tools.

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

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

The description discloses key behavioral traits beyond annotations: it does NOT crawl or inspect existing pages, uses AI-estimated rather than measured data, and creates content that cannot reach an audience on its own. This adds important context about side effects and data reliability that annotations do not 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 compact and every sentence adds value: purpose, exclusions, sequencing, workflow, and capability note. It is front-loaded with the core behavior and uses clear structure without redundancy.

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

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

For a single-parameter tool with no output schema, the description adequately covers inputs, expected behavior, non-behaviors, workflow integration, and return handling ('Relay the returned proposals'). It fully equips 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?

Schema coverage is 100% with a clear description for siteId. The tool description enriches parameter meaning by explaining that siteId refers to a connected site with configured pillars, which is not explicit in the schema. This goes beyond the baseline 3 for high 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 states a specific verb ('brainstorm') and resource ('question-shaped topics with rationale') and clarifies what the tool does not do (crawl site, inspect pages, use measured search data). It clearly distinguishes this from sibling tools like autoseo_configure or autoseo_generate_post by framing it as an early-stage ideation step.

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 workflow guidance is provided: call after autoseo_connect_site and autoseo_verify_site, before autoseo_configure. It also explains why (user approves a concrete topic list) and how to relay results, and notes the capability constraint ('Safe for a draft-only agent token') for appropriate invocation 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 annotations, the description reveals that it sends a signed test request, checks wp_rest and git_pr connections, and returns a capabilities map. It also notes the active-org requirement and safety for draft-only tokens. The 'CAPABILITY: draft' sentence adds some confusion but does not contradict 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 longer than average but every sentence contributes concrete guidance (when to use, what it verifies, troubleshooting, return value). The final CAPABILITY sentence is slightly confusing but not entirely wasted.

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

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

With no output schema, the description explicitly states it returns the refreshed capabilities map, explains failure modes (404/405), and ties into adjacent tools (autoseo_configure, autoseo_generate_post). It provides a self-contained decision framework for an AI agent.

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 complete coverage of the single 'id' parameter with a source reference. The description adds meaningful constraints—'must belong to the active org'—and clarifies its role in the verification flow, going 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 and resource: 'Re-run the capability probe for a connected site', and the title 'Verify a connected site' matches. It clearly distinguishes this verification tool from siblings like autoseo_configure and autoseo_generate_post.

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

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

It explicitly instructs when to call: after deploying the /autoseo-publish endpoint and before configuring or generating. It also specifies re-call scenarios (secret rotation, infrastructure migration) and how to interpret 404/405 responses, giving clear workflow context.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; description adds crucial context by emphasizing SIDE-EFFECT-FREE, explains that the connection only comes after user action, and warns the agent not to assume a connection. Also details authUrl/expiresAt/instructions return and error code meanings.

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 and front-loaded with the core action. Although long, each sentence carries essential operational guidance (side-effect warning, expiration, flow, errors) that prevents misuse. Slightly verbose but 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?

Despite no output schema and zero params, the description fully specifies the output fields, the user flow, follow-up status tool, and error semantics. This is a complete operational specification for 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?

No parameters exist (input schema empty), so baseline 4 applies. The description adds value by explaining the return contract (authUrl, expiresAt, instructions) and how to relay them to the user, which is beyond 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 opens with "Generate a 'click to authorize GitHub' link for Build-in-Public Autopilot", using a specific verb and resource. It explicitly contrasts with actual connection ("never connects...") and points to sibling build_in_public_status for checking outcomes, distinguishing itself from related 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?

Clearly states when to use: when you need an authorization URL. Provides explicit exclusion: 'the agent must NOT treat it as having connected a repo.' Also directs to build_in_public_status for checking the outcome, offering an explicit alternative. Covers error handling and action steps.

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 include readOnlyHint: true, idempotentHint: true, and destructiveHint: false. The description reinforces this with 'Never mutates anything' and 'CAPABILITY: read — side-effect-free.' It also discloses the full return shape, including reset semantics like mode defaults, which goes beyond the annotations. 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 dense but every sentence earns its place: a front-loaded READ-ONLY summary, a complete field listing with inline explanations, concrete use cases, a mutation guarantee, and a sibling relationship note. It packs substantial value without redundancy.

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

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

Given there is no output schema, the description compensates by fully enumerating the response structure, including nested objects (repos, lastDraft) and explained enums (mode, postMode). It also links to list_approvals for related pending drafts, making it contextually complete for a status tool.

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

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

The tool has zero parameters, and the input schema is empty. Per the rubric, 0 params baseline is 4. The description adds meaningful output semantics (fields and their meanings), but no parameter-specific guidance is needed. It does not detract from parameter understanding.

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

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

The description opens with a specific verb+resource: 'READ-ONLY status of the org's Build-in-Public GitHub connection.' It clearly specifies the tool's purpose and distinguishes it from siblings like build_in_public_connect_link (which generates the connect link) by listing concrete use cases such as verifying setup and checking the latest draft.

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 it to answer "is build-in-public set up?", to verify a connect link the user was given actually got completed, or to see the latest draft.' It also gives an alternative for a related task: 'Drafts awaiting review also appear in list_approvals under source build-in-public.' This directly guides when to use this tool versus a sibling.

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

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

Annotations already declare destructiveHint=true, so the description is not responsible for that. It adds useful context: the post must belong to the active org and the operation is safe for a draft-only token. However, the CAPABILITY line claiming it 'creates content' is misleading for a delete tool and harms transparency, though it doesn't 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 first sentence is front-loaded and effective, but the CAPABILITY sentence is confusing and doesn't serve a clear purpose in the context of deletion. This makes the description less concise than it could be, though it is still short.

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

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

For a tool with one parameter and clear annotations, the description is mostly adequate. It covers the core action and org constraint, but it doesn't clarify whether published posts can also be deleted or what happens if the post doesn't exist. The confusing CAPABILITY sentence also creates a gap in understanding the tool's exact scope.

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 for the sole 'id' parameter (described as 'Post id'), so the description doesn't need to explain it. The description adds no extra meaning about the parameter, so the baseline score of 3 applies.

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

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

The description begins with 'Delete a post (e.g. to cancel a scheduled one)', which clearly identifies the verb and resource and distinguishes it from scheduling/publishing tools. However, the later CAPABILITY line about 'creates content' is confusing and slightly obscures the delete 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?

It provides a concrete use case ('cancel a scheduled one') and a key constraint ('Must belong to the active org'), which gives clear context. But it doesn't explicitly mention when not to use it or name alternatives like reject_draft or unpublish.

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/openWorldHint/idempotentHint. The description adds vital behavioral context: the tool cannot complete the connection itself, requires a signed-in human to click through an OAuth popup, and warns agents not to claim the account is connected until the user confirms. This prevents a critical misuse and goes well 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?

The description is five sentences, each serving a distinct purpose: tool's core action, deep-link behavior, provider constraint, human-interaction caveat, and capability statement. Critical information is front-loaded and every sentence earns its place without unnecessary 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 the tool's simplicity (one enum parameter, no output schema, strong annotations), the description fully covers what it does, what it returns (a link), how it must be used (relay to user), and its side-effect-free nature. It even covers the caveat about not claiming connection until user confirmation, making it complete for practical use.

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

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

With schema description coverage at 0%, the description compensates by explicitly enumerating valid provider values: 'provider must be one of: instagram|twitter|tiktok|facebook|pinterest|youtube|linkedin|reddit|threads.' It also adds the semantic role 'for the chosen provider', clarifying that the provider selects which social network to connect. This is adequate for a single enum parameter.

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 'Return a link the user opens in a browser to connect a social account via OAuth', immediately stating the exact verb, resource, and mechanism. It further specifies the deep-link behavior and distinguishes it from sibling tools like build_in_public_connect_link, which serves a different connection 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 gives clear usage context: it must be used when a human is required to complete OAuth, and explicitly instructs agents to 'relay this link to the user and do not claim the account is connected until they confirm'. It stops short of naming alternative tools or exclusion conditions, so it lacks full 'when-not-to-use' guidance beyond the human-interaction caveat.

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, it discloses idempotency details (resends update still-pending drafts, never duplicates or resurrects decided ones), platform alias mappings, thread behavior for segments, link appending at approval, schedule_hint semantics, style constraints, and capability (`draft`). This is rich behavioral context that significantly exceeds what annotations alone 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 dense but every sentence adds value: primary purpose, idempotency, alias, thread/link/schedule semantics, style guidelines, prerequisite reading, and capability. It is front-loaded with the core action and flows logically through behavior, parameters, and context without 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 tool's complexity (multi-platform, segments, media, schedule, idempotency, approval flow) and no output schema, the description covers all essential behavioral and usage aspects. It explains prerequisites, safety profile, style requirements, and what happens on resubmission, leaving little ambiguity for an agent.

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 67%, the description compensates by explaining platform aliases, segments (1 = single post, 2+ on twitter = thread), link appended to final segment, and idempotency behavior for external_ref. These meanings go well beyond the schema's basic type 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 submits a batch of platform drafts for one engine artifact (e.g., a digest issue), using the specific verb 'submit' and identifying the resource. It also distinguishes itself from the alias `create_drafts` and clarifies the generic mechanism, so it is clearly differentiated from siblings like publish_post or schedule_post.

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

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

The description provides strong context: drafts are always pending approval and never auto-publish, the alias `create_drafts` is equivalent, and it instructs to read recent posts with list_posts before drafting to match voice. It doesn't explicitly state 'use this instead of X when Y', but the pending-approval behavior and mention of approve_draft make the intended use 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 goes far beyond the sparse annotations (all false) by disclosing that the funnel is inactive, cannot reach an audience, and is safe for a draft-only token. It also details matching behavior (normalized whole keywords/phrases), timing (30-120 seconds), and message constraints (exactly one {{link}}; publicReplyTemplate optional and OFF when omitted). This provides rich behavioral context with 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 three sentences plus a capability line, front-loading the primary purpose. Every sentence adds distinct value: the first defines the action, the second explains functional behavior, the third covers activation and safety. No filler or redundancy.

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

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

The description covers safety, activation limitations, timing, matching behavior, and content constraints, which is substantial given the tool's complexity. It does not describe the return value or what happens after drafting, but with no output schema, the description still provides enough context for an agent to invoke the tool and handle the draft outcome appropriately.

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

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

With schema description coverage at 56%, the description adds meaning for several otherwise undocumented parameters: keywords are normalized whole keywords/phrases, dmTemplate must contain exactly one {{link}}, leadUrl is substituted for {{link}}, and publicReplyTemplate defaults to OFF when omitted. It does not clarify name or dailyCap, but the schema bounds dailyCap and name is generic, so the description meaningfully compensates for schema gaps.

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

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

The description clearly states the tool creates an INACTIVE beta Instagram comment-to-DM funnel for one already-published post. It specifies the exact verb, resource, and scope, and distinguishes itself from sibling tools like create_drafts and list_dm_funnels by emphasizing the draft-only, Instagram-specific funnel behavior.

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: use this for drafting a comment-to-DM funnel on a published post. It explicitly states the tool cannot activate the funnel and requires a signed-in human for activation, which serves as a when-not-to-use indicator. However, it does not name alternative tools (e.g., list_dm_funnels for viewing or schedule_post for scheduling), so it falls short of full alternative 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 critical behavioral traits (always pending_approval, never auto-publish, idempotent on external_ref, platform aliases, segment behavior, link appending, schedule_hint semantics, CAPABILITY). However, annotations set idempotentHint=false while the description claims idempotency on external_ref, a direct contradiction. Per rubric, this scores 1.

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?

Though long, every sentence earns its place by addressing a functional aspect—idempotency, approval flow, aliases, segmentation, style rules, and sibling relationship. Critical instructions are front-loaded, 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?

Given the complexity of batch draft creation, the description covers all operational nuances: idempotency, approval chain, provider aliases, segment rules, writing style, and relationship to siblings. No output schema exists, but for a creation tool, return values are less critical and the description provides complete context 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?

The description adds substantial meaning beyond schema descriptions: platform aliases (x/x_post/x_thread → twitter), segment count semantics (1 = single post, 2+ on twitter = thread), link appended at approval, schedule_hint 'optimal' or future ISO datetime, and brand tag distinction from BrandVoice. This far exceeds the 67% 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 opens with a specific verb ('Submit') and resource ('batch of platform drafts for one engine artifact'), clearly stating what the tool does. It also distinguishes from sibling create_digest_drafts by explaining they share the same mechanism but this name is preferred, providing clear differentiation.

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 directs the agent to call prompt_suggest first and base the prompt on the top result, and to read recent posts via list_posts to match voice. It also advises to prefer this name over create_digest_drafts for new integrations and notes it is safe for draft-only tokens, giving clear when-to-use 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?

Rich behavioral disclosure well beyond annotations: grounding claims in verbatim quotes, deterministically dropping unquotable claims, planning different angles per platform, running length/groundedness/originality gates, landing PENDING, never publishing, returning 202 with ingestId and polling via get_source_status, plus detailed style rules. 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 long but information-dense. Every sentence contributes: process, guarantees, async behavior, style guide, and safety. It is front-loaded with a clear one-liner. Slightly run-on in places but justifiably detailed for a complex tool.

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

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

For a complex async tool with no output schema, the description covers lifecycle (202 + ingestId), polling, failure modes (EMPTY, FAILED), platform constraints, style expectations, and capability safety. It even cross-references get_source_status and list_posts. 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 83% of parameters well. Description adds value by explaining the relationship between text and urls ('give it one or more URLs, pasted text, or both' and use text for paywalled/JS-rendered). It also adds platform behavior (only connected platforms) and clarifies scheduleHint is applied at approval. Minor gaps remain for brand/title but schema already documents them.

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 a specific verb and resource: 'Turn RAW MATERIAL into platform-native post drafts.' It distinguishes from siblings like create_drafts and schedule_post by emphasizing it fetches/extracts URLs or text, drafts in native format, and never publishes. The scope 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 clear usage context: when to use with URLs, pasted text, or both; when to use text (paywalled/JS-rendered); and that only connected platforms are drafted for. It doesn't explicitly name alternative tools or say 'use this instead of create_drafts', but the source-based workflow is implied clearly 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?

Description claims 'Idempotent: re-finalizing the same key returns the existing asset,' which directly contradicts the annotation idempotentHint=false. Per the rubric, any contradiction between description and annotations results in a score of 1.

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 efficient, covering step, precondition, behavior, return value, usage, capability, and safety in a compact format. It is slightly dense but every sentence contributes meaningful guidance; no fluff or redundancy.

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

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

Despite lacking an output schema, the description explains the return value (MediaAsset with publicUrl) and its downstream use. It also addresses idempotency, capability (draft), and safety for draft-only tokens, making it highly complete for a multi-step flow with no output schema.

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

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

Input schema provides full descriptions for all three parameters (key, contentType, size), achieving 100% coverage. Description adds only reinforcement to use the same values from step 1, but does not add new semantic details beyond the schema, 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?

Description clearly states the tool's purpose: 'Registers the object as a MediaAsset and returns it' as step 3 of the media upload flow. It distinguishes itself from sibling tools (prepare_media_upload, upload_media) by specifying its position in the sequence and 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?

Explicitly states when to call: 'AFTER you have PUT the raw bytes to the presigned uploadUrl from prepare_media_upload.' Also directs the return value usage: 'publicUrl is what you pass to schedule_post mediaUrls.' Provides clear context for the agent to invoke correctly without confusion.

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 mutability and open-world side effects; the description adds substantial context: credit costs by provider, rate-limit 429 behavior, image hosting prerequisites, the muted ShortSpec scene plus voiceover/caption processing, and the 'draft' capability meaning content cannot reach an audience alone. This goes well beyond the annotations and provides clear behavioral expectations. No contradiction found.

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 quite long and includes tangential writing-style guidance (em-dashes, hashtags, voice matching) not directly related to invoking this tool. It is front-loaded with the core purpose and genre breakdown, but not every sentence earns its place, making it heavier than necessary for an agent to parse.

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 covers the primary return value (hosted mp4 publicUrl), the full media upload workflow, credit costs, and rate limit behavior. However, it does not specify whether generation is asynchronous or list all possible response fields, leaving some gaps for a complex tool with 20 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 high (90%), so the baseline is 3. The description adds genre-specific semantics for parameters: imageUrl is explicitly REQUIRED for asmr_loop, referenceImageUrls are for character_series consistency, timerLine for pov_historical, and provider routing/credit costs. This adds meaningful context beyond the schema's own field descriptions.

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

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

The description clearly states a specific action ('Generate a FINISHED, PUBLISHABLE vertical (9:16) short video') and output ('hosted mp4 publicUrl'), distinguishing it from siblings by describing the full production pipeline (voiceover, karaoke captions, ffmpeg assembly). It differentiates from other content tools by emphasizing the finished, publishable result and the workflow with schedule_post.

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

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

Provides explicit workflow guidance: call prompt_suggest first, prepare images via prepare_media_upload, and pass the resulting publicUrl into schedule_post. It also states when to use each genre and when to override the provider, and notes the draft-only capability. However, it does not explicitly name sibling alternatives like shorts_generate, so it stops short of full exclusion criteria.

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 read-only, non-destructive, and idempotent, and the description reinforces this with 'CAPABILITY: read — side-effect-free.' Beyond annotations, it discloses token-refresh semantics (e.g., X access tokens live 2h, past expiresAt with hasRefreshCapability=true is normal), which is crucial behavioral context for interpreting integration status and prevents false conclusions.

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 'START HERE' but then runs on as a massive single paragraph enumerating a long list of capabilities. While the detail is useful for a capability map, the lack of structural breaks and its length hurt readability; it is not concise.

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

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

For a zero-parameter tool without an output schema, the description is exceptionally complete: it lists all major content areas (lifecycle, thread rules, platformData, org model, metrics, AutoSEO, DM Funnels, integrations, etc.) and provides operational semantics like token refresh behavior. No gaps are apparent for the tool's purpose.

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

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

The tool has zero parameters and the schema is empty (100% coverage), so the description need not explain parameters. The baseline for 0 params is 4, and the description adds no parameter info, which is appropriate.

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

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

The description uses the specific verb 'Returns' and identifies the resource as the 'authoritative machine-readable capability map', then enumerates its contents in detail. It distinguishes itself from siblings by positioning itself as the start-here map and explicitly saying 'Trust this over inferences from other tools' raw fields.'

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: 'START HERE when mapping what TimeToPost can do.' It also gives an alternative-avoidance directive: 'Trust this over inferences from other tools' raw fields,' which clarifies when this tool should be preferred over sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's 'CAPABILITY: read' is redundant. However, it adds behavioral context about aggregation scope (all posts tagged with the slug) and the output metrics, which is helpful. It doesn't disclose edge cases like no matching posts.

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 purpose and metric list, followed by usage context. However, the final 'CAPABILITY: read — side-effect-free' sentence repeats information already in annotations, adding minimal 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?

For a simple read-only aggregation tool with one parameter and full schema coverage, the description covers the purpose, input prerequisites, and output metrics. It could be more complete by mentioning the response format or behavior with no matching posts, but overall it's sufficient.

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

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

The single 'brand' parameter is fully described in the schema as 'Brand slug from list_brands'. The description reinforces this by saying 'given brand/niche slug' and pointing to list_brands, but adds no new semantics 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 identifies the tool as a per-brand engagement rollup, listing the specific metrics (likes, comments, shares, etc.) and the scope (across all posts tagged with the given brand/niche slug). It distinguishes from siblings by emphasizing the brand/niche slug and references list_brands for discovering valid slugs.

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

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

The description implies usage for per-play KPI dashboards and requires using list_brands to obtain valid slugs. It provides clear context but doesn't explicitly state when to prefer this over other engagement summary tools, nor does it rule out 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 adds no behavioral information beyond what the annotations already provide. The line 'CAPABILITY: `read` — side-effect-free' merely restates the readOnlyHint and destructiveHint annotations, without adding context such as output format, pagination, or access requirements.

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

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

The description is concise and front-loaded with the key information. However, the 'CAPABILITY: read' line is redundant with the annotations and does not earn its place, slightly reducing the score from a perfect 5.

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 simplicity (no parameters, no output schema), the description gives a basic idea but lacks specificity about what 'engagement metrics' include (e.g., likes, shares, reach), time periods, or aggregation granularity. It is minimally viable but leaves room for interpretation.

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

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

The tool has zero parameters and the schema coverage is effectively 100% (vacuous). The description is not required to explain parameters since there are none, earning a baseline score of 4.

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

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

The description clearly identifies the resource as 'Aggregated engagement metrics for the active org,' which distinguishes it from siblings like get_engagement_by_tag and get_post_metrics by emphasizing org-level aggregation. However, it lacks an explicit verb such as 'retrieves' or 'returns,' relying on the tool name to convey the action.

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 no guidance on when to use this tool versus alternatives. It only states the scope ('for the active org'), but does not mention related tools like get_engagement_by_tag or get_post_metrics, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds context about the data source ('historical performance') and the advisory nature ('suggested'), which is valuable beyond the annotations. The 'CAPABILITY: read' note is redundant but consistent, with 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?

The description is a single concise sentence plus a capability note. It is front-loaded with the core purpose and includes no extraneous information, making it highly efficient.

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

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

For a parameterless read-only tool with no output schema, the description sufficiently covers what it returns and the basis for the suggestions. It lacks explicit usage context, but that is more relevant to the usage guidelines dimension and does not undermine overall completeness for selecting 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?

The tool has zero parameters, so the description has no need to explain them. Schema coverage is 100% vacuously, and the baseline for zero parameters is 4. No parameter-related gaps exist.

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

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

The description clearly identifies the tool as providing suggested best posting times based on historical performance. It specifies a distinct resource and scope, though the verb is implied by the tool name rather than stated. It does not explicitly distinguish from siblings, but the resource is specific enough.

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 the tool is useful for identifying optimal posting moments but provides no explicit guidance on when to use it versus alternatives like scheduling or metrics tools. There are no exclusions or direct references to sibling tools, making the usage context somewhat implied.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds meaningful behavioral context: the post 'must belong to the active org' and explicitly states it is 'side-effect-free.' It also outlines what data will be returned, which goes 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 compact and well-structured: the first line states the core action, the middle lists return fields, and the final sentence provides usage guidance and capability. Every sentence earns its place with no unnecessary 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?

Despite having no output schema, the description thoroughly explains the return values, including status enum values, timestamps, mediaUrls, and platformData with per-platform permalinks. It also covers the org scoping constraint. This is complete for a simple read-only tool.

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

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

Schema coverage is 100%—the only parameter 'id' is described simply as 'Post id.' The description enhances this by clarifying that the id must refer to a post in the active org, adding semantic context about the parameter's scope and validity.

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 and resource ('Fetch a single post by id') and clearly distinguishes itself from sibling tools like list_posts by focusing on a single post. It also enumerates the fields returned, leaving no ambiguity about what the tool does.

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 a clear use case: 'Use after publishing to confirm the post actually went out and to get platform permalinks.' This gives concrete when-to-use guidance, though it does not explicitly mention alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context by disclosing that metrics arrive via periodic sync and recent posts may be empty until the next cycle. This goes beyond the annotations and is important for setting 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 three sentences long, each adding distinct value: purpose, data freshness caveat, and alternative tool. It is front-loaded with the core functionality and has no redundancy or filler.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, behavior, and parameter scope. The sync caveat and explicit alternative complete the picture, leaving no significant gaps.

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

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

The schema has 100% coverage, with a description for post_ids. The description mentions 'one or more post ids' aligning with the array parameter, but adds no additional formatting or syntax details. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns per-post engagement metrics (impressions, likes, comments, shares, etc.) for one or more post IDs. It uses a specific verb and resource, and explicitly distinguishes itself from get_engagement_summary for aggregate data.

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

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

The description explicitly directs users to get_engagement_summary for the org-wide aggregate, indicating when not to use this tool. It also notes the periodic sync behavior, helping users understand when to expect data, especially for very recent posts.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: it is 'side-effect-free', explains the 'thin' extraction exclusion (under 200 words, excluded rather than hallucinated), and warns that needsFactCheck=true drafts require human approval before publishing. These go well 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 four sentences, front-loaded with the core purpose. It uses compact notation (status arrows, quoted 'thin') to convey a rich return payload and two important caveats. Every sentence earns its place; no redundant or filler content.

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

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

Since there is no output schema, the description must explain return values, and it does comprehensively: the status chain, evidence-backed brief, angle plan, per-item extraction result, pending drafts, and the fact-check flag. For a single-param polling tool, this is fully complete.

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

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

Schema coverage is 100% for the single parameter ingestId, and the schema already states 'Ingest id returned by create_posts_from_source'. The description merely echoes this provenance without adding new parameter syntax, format, or edge-case details. 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: 'Poll one source ingest by id'. It clearly states the ingest originates from create_posts_from_source, and enumerates the full return payload (status, brief, angle plan, extraction results, pending drafts). This distinguishes it from sibling tools like get_post or list_sources.

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 indicates when to use the tool: after create_posts_from_source returns an ingest id. It provides clear context for polling but does not explicitly list alternatives or when-not-to-use scenarios. This is a minor gap, so 4 rather than 5.

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

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

Beyond the annotations (readOnly, idempotent, destructive false), the description adds substantive behavioral context: the no-caching requirement, the constraint that disabled interactions must be sent as false, and that the returned list of audiences is the only allowed set. It also confirms 'side-effect-free', aligning with annotations, and explains how to use results in a workflow.

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

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

The description is a dense paragraph, but every sentence earns its place: purpose, usage, return fields, caching rule, and parameter note. It is slightly long but tightly packed with practical information; a more structured list or split into sentences would improve scannability.

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

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

Given there is no output schema, the description thoroughly enumerates key returned fields (creator nicknames, privacy options, interaction flags, max duration) and explains their significance for scheduling. It also covers prerequisites (accountId from list_integrations), usage rules, and the read-only nature, making it complete for a tool of this 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?

The schema already covers accountId with a description matching the one in the tool description (`Integration id of the TikTok account (from list_integrations). Optional when only one is connected`). The description essentially repeats this information, adding no new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'Read a connected TikTok account's CURRENT posting settings, straight from TikTok', using a specific verb and resource. It distinguishes itself from siblings by explicitly tying its use to schedule_post and emphasizing it is a read 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?

The description gives explicit when-to-use guidance ('Call this before every TikTok schedule_post') and a critical no-caching rule. It also references list_integrations for accountId and provides a condition for omitting it, but it does not explicitly state when not to use this tool or name alternative tools for related 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?

Beyond annotations, the description discloses detailed behavioral side effects: appends keyword text to config.topics, marks rows in_plan, and does not trigger publishing. It also adds safety context with CAPABILITY `draft` and the assurance that content cannot reach an audience on its own. This is valuable, non-redundant behavioral disclosure.

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

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

The description is concise and front-loaded with the primary action, followed by essential side effects and safety info. Every sentence contributes meaningful information without redundancy or excessive 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 moderate complexity, the description covers purpose, exact modifications, non-behaviors, approval gating, and capability classification. With all parameters documented in the schema and no output schema, the description provides sufficient context for an agent to 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 descriptions already cover all three parameters at 100%. The tool description adds high-level context about what happens to keyword rows but does not add specific parameter-level details beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Add selected persisted keyword rows to an existing AutoSEO content plan.' It identifies the exact action, target resource, and distinguishes itself from tool siblings by explicitly noting it 'does not generate or publish an article.' This differentiates it from autoseo_generate_post and other publication 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 provides context on when to use the tool by clarifying what it does not do ('does not generate or publish an article') and that later generation is gated by approval. However, it does not explicitly name alternative tools or specify exact conditions for use, stopping short of a full when/when-not/alternatives breakdown.

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 that the tool persists data (write operation), returns estimated data with source='estimated', never fabricates exact numbers, and warns not to describe estimated bands as measured. It also mentions a future live provider and reinforces safe use with draft-only tokens. This goes well beyond the annotations, which only indicate readOnlyHint=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 multi-sentence but each sentence carries meaningful detail: purpose, data quality caveats, source handling, and capability safety. It is front-loaded with the primary purpose and structured logically, though slightly longer than strictly necessary.

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

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

Given there is no output schema, the description explains the return shape (source='estimated', volume band, KD levels, null exact metrics) and the persistence behavior. It does not cover error cases or pagination, but for a research/persist tool the description provides sufficient context to understand what the tool does and returns.

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

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

Schema coverage is 100% with clear descriptions for seed, seedKind, siteId, and country. The description reinforces that seed can be a keyword or site/URL and mentions Slice A behavior, but does not add significant new parameter-level semantics beyond what the schema already provides. 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 states 'Research and persist keyword opportunities for a seed keyword or supplied site/URL.' It uses specific verbs (research/persist), names the resource (keyword opportunities), and distinguishes itself from sibling tools like keyword_add_to_plan or create_posts_from_source by focusing on the research and persistence action.

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 that the tool is for research and persistence, and includes a safety note about being safe for a draft-only agent token. However, it does not explicitly compare this tool to alternatives or mention when not to use it, leaving the usage decision mostly implied.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial context: side-effect-free behavior, the unified aggregation semantics, normalized return shape with per-source counts, and the meaning of the actions array. It fully discloses what the tool does and what it cannot do, going beyond the annotations without contradicting them.

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

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

The description is longer than average but front-loads the core purpose and organizes detail logically. Most sentences add distinctive value, though the CAPABILITY line and 'never approves or rejects' are slightly redundant with the annotations. Still, the density is justified for a multi-source aggregation tool.

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

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

With no output schema, the description compensates by specifying the exact common shape, per-source counts, and the actions array containing REST endpoints. It also gives full context about the four sources and how this tool relates to approval workflows, making it very complete for an agent to 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 coverage is 100% and both parameters already have descriptive enum-based documentation. The description adds a little context (e.g., 'narrows to one queue' and default PENDING) but mostly reinforces what the schema already states. This aligns with the baseline 3 for high 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?

Description states a specific verb (list/read) and resource (unified approvals rail across four sources) with a clear scope. It also distinguishes itself from sibling tools by explicitly noting it only reads and never approves/rejects, with approve_draft/reject_draft named as the mutating 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?

Explicitly describes when to use the tool (read-only view of pending approvals across all four automation sources) and provides exclusions: it never approves or rejects, and approval for non-posts sources remains a dashboard action. The optional source/status filters are also called out as selection mechanisms.

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, idempotent, and non-destructive. The description adds value by disclosing the 404 error behavior and confirming side-effect-free operation, which 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?

The description is concise and well-structured: first sentence states purpose and output, second provides usage context, third notes error behavior. Every 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?

For a zero-parameter list tool with no output schema, the description fully covers purpose, usage, expected return fields, and failure mode. It is self-contained and actionable.

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

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

There are no parameters, so schema coverage is complete by default. The description does not need to explain parameters, and it appropriately focuses on the tool's output and prerequisites.

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

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

The description clearly states the tool lists Pinterest boards with specific fields (id, name, privacy, pin count). It distinguishes this from sibling tools like list_integrations by explicitly scoping to Pinterest boards.

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: call before schedule_post with a Pinterest target, and explains that boardId must match one of the returned ids. Also notes the 404 condition when no integration is connected, giving clear when-to-use and prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by explicitly stating 'CAPABILITY: read — side-effect-free,' and adds behavioral context about how brands are auto-registered through other tools. This explains why the list may change and what the returned data represents, which is valuable context 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?

The main purpose is front-loaded in the first sentence. The following sentences provide essential background on brand semantics, auto-registration, and the BrandVoice distinction. While the description is longer than the absolute minimum, each section (TERMINOLOGY, CAPABILITY) earns its place by preventing real confusion. It could be tightened, but remains well-structured and readable.

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

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

For a zero-parameter, no-output-schema tool, the description is complete. It covers what is returned (profiles with post counts), how brands are created (auto-registration), and the critical distinction between 'brand' and 'BrandVoice'. The annotations handle safety concerns, and the description provides enough context for an agent to select and invoke the tool correctly without needing further details.

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

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

The tool has zero parameters, and the schema confirms this with 100% coverage. The description adds org-level scoping ('the org's') and output information (post counts) but nothing specific to parameters since there are none. Baseline for zero-param tools is 4, and there are no gaps to compensate for.

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 org's brand/niche profiles with post counts.' It uses a specific verb and resource, and the detailed explanation of what a 'brand' is (a per-post niche/play tag) distinguishes this tool from sibling list tools like list_boards or list_posts. The BrandVoice disambiguation further eliminates potential confusion with other 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 explains the context of use: to view brand/niche profiles and how engagement rolls up per play. It also gives the important prerequisite that brands auto-register the first time a tag is used on schedule_post, publish_thread, or create_digest_drafts, so no explicit creation step is needed. While it doesn't explicitly name alternative tools or exclusion conditions, the context is clear enough for an agent to choose this tool appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds valuable detail beyond these: it lists the returned data (Draft/Active state, account and post snapshots, keywords, today's reserved send usage, poll errors, reconnect state) and explicitly states 'side-effect-free' and 'no MCP activation tool,' which are extra behavioral traits.

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 concise at two sentences and front-loads the core purpose. However, it contains some redundancy: 'This is read-only' and 'CAPABILITY: read — side-effect-free' largely repeat the annotations, and the long list of return fields makes the first sentence a bit dense.

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

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

For a read-only list tool with no output schema, the description provides a strong return-field inventory and a clear safety profile, which helps an agent understand what to expect. However, it lacks parameter explanations and does not mention usage alternatives, so it is not fully complete for making an informed invocation decision.

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

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

Schema description coverage is 0%, and the description does not mention any of the five parameters (limit, scope, active, cursor, integrationId). The schema provides names and constraints, but the description fails to compensate for the low coverage, leaving parameter meaning unexplained.

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 ('List') and identifies the exact resource ('this organization's post-scoped Instagram DM funnels'), listing several included fields. It clearly distinguishes from siblings like list_funnel_hits (which counts hits) and create_dm_funnel (which creates) by focusing on listing funnels and their state.

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

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

The description implies usage for when you need to view DM funnels, and the 'post-scoped' qualifier provides some context. However, it does not explicitly name alternatives or state when not to use this tool. The note 'deliberately no MCP activation tool' is a caveat but not a substitute for explicit when-to-use versus sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by noting the active-org scope, the side-effect-free capability (though redundant with annotations), and the postId behavior for POSTED drafts, which enriches the agent's understanding beyond structured fields.

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

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

The description is three short sentences, front-loaded with the core action and resource, then filters, a special case, and a capability note. Every sentence adds substantive value with zero 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?

For a simple list tool with two optional parameters and no output schema, the description covers scope, filters, and the notable return-field behavior (postId). It does not enumerate all possible return fields, but given the tool's simplicity and strong annotations, this is sufficient.

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

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

With 0% schema coverage, the description compensates by naming both parameters ('status' with allowed values and 'brand' as a filter), but it does not specify the brand parameter's format or any default behaviors. This meets the minimum compensation threshold but lacks depth, especially since the status enum is already 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+scope: 'List engine-submitted drafts for the active org.' This clearly distinguishes it from siblings like list_posts (posts vs. drafts) and list_approvals (approvals vs. drafts), while also noting the active-org scoping.

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 states the optional filters ('Optional status... and brand filters') and provides a follow-up path ('POSTED drafts carry a postId you can follow with get_post'), giving clear context on when the tool is used. It does not explicitly state when not to use it, but the resource name and sibling context make exclusions apparent.

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, so the description adds value by explaining the meaning of a hit and disclosing failure-queue visibility and dmStatus lifecycle. This is context beyond the annotation flags.

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 first sentence is information-dense and front-loaded with the resource. However, the final 'CAPABILITY: read' line is redundant with the annotations, making it slightly less 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?

The description lists the output fields, which is helpful since there is no output schema. However, it omits parameter usage and pagination behavior, leaving gaps for a tool with four 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 0% and the description does not explain any of the four parameters (limit, cursor, status, funnelId). It only mentions 'one DM funnel' implicitly, but no details on filters or pagination.

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 'List captured comment evidence and delivery outcomes for one DM funnel' with a specific verb and resource. It includes field details and distinguishes this from sibling tools like list_dm_funnels by focusing on hits for a single funnel.

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 says 'Read-only failure-queue visibility; a hit means a matching commenter, not a verified link conversion,' which sets expectations for when to use the tool. It clearly implies this is for inspecting funnel hits, but does not explicitly contrast with list_dm_funnels or other list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the CAPABILITY: read line reinforcing this but offers no additional behavioral details such as return format, pagination, or auth requirements.

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

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

Two concise sentences with no wasted words. The primary purpose and capability are both stated efficiently.

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 parameterless list tool with no output schema, the description fully covers what the tool does (lists integrations and statuses) and its scope (active org). No additional context is needed.

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 zero parameters, so there is no parameter documentation burden. The description appropriately mentions the scope (active org) as the implied filter, earning a solid baseline 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 the tool lists social/platform integrations for the active org with their connection status. The verb 'list' and specific resource distinguish it from sibling tools like list_posts or list_boards.

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: it targets the active org and is side-effect-free. However, it does not explicitly mention when to use this tool over alternatives like list_boards or list_posts, though the distinct resource makes the choice fairly obvious.

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 idempotentHint=true. The description adds the 'active org' scope and 'side-effect-free' context, which are useful behavioral details beyond the annotations. 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 two short sentences, front-loaded with the core purpose, and contains no filler words. Every word contributes meaning.

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 list tool with one optional parameter and no output schema, the description adequately covers the core behavior: listing posts for the active org with an optional status filter. It would benefit from stating return value expectations, but given the simplicity, it is sufficiently complete.

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

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

Schema description coverage is 100% with the 'status' parameter already having a description and enum. The description only restates 'Optionally filter by status' without adding additional meaning or usage details, so it adds no 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 clearly states 'List posts for the active org' which identifies the specific verb and resource. It distinguishes from siblings like get_post (singular) and list_drafts (different resource). The optional filter by status adds specificity.

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

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

The description implies usage for retrieving posts in the active org, but gives no explicit when-to-use guidance or alternatives. It doesn't mention using get_post for single posts or list_drafts for drafts, so the agent must infer the scope from the name and context.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by disclosing newest-first ordering and the specific return content (status, platforms, draft counts, extraction results). It redundantly restates read-only, but that 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?

Two sentences, front-loaded with the core purpose and return details. The read-only note is redundant given annotations but does not waste significant space. 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?

With zero parameters and no output schema, the description is complete for a simple read-only list tool. It explains the scope (this org), ordering (newest first), and the full set of returned fields, leaving no significant unanswered questions.

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

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

There are zero parameters, so schema coverage is trivially 100%. Per the rubric, zero-parameter tools get a baseline of 4; there are no parameter semantics to explain, and the description appropriately omits parameter details.

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 the verb 'list' and resource 'source ingests', with details on ordering and return fields (status, planned platforms, draft counts, per-item extraction results). This differentiates it from sibling list tools like list_integrations and list_posts.

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?

Context is clear: it's for viewing the org's recent source ingests, which is distinct from integrations, posts, or drafts. However, it does not explicitly mention exclusions or alternative tools, so it falls short of a 5.

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

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

With annotations all false, the description carries the full burden. It discloses that the tool starts/resumes provider minting (a side effect), requires Presenter Pack, and creates content that cannot reach an audience on its own. It also reassures safety for draft-only agent tokens, adding valuable behavioral context 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 three focused sentences, front-loaded with the main action. Each sentence adds essential context: what it creates, prerequisites, and safety/behavioral notes. 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 the complexity of 16 parameters and no output schema, the description is incomplete. It covers purpose and safety but omits parameter meanings, expected return values, and detailed behavior. The high parameter count and zero schema coverage leave significant gaps that the description does not fill.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. However, it provides no parameter-specific information, only mentioning the general action of creation. The 16 parameters remain completely undocumented, leaving the agent without semantic guidance.

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 a DRAFT AI Presenter persona and also starts/resumes provider minting, with a specific verb and resource. It distinguishes itself from siblings like persona_list and persona_status by focusing on creation and the draft capability.

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 on when to use this tool: when creating a draft persona and needing to start/resume minting. It also notes the Presenter Pack requirement when billing is enabled, offering practical prerequisite guidance. It does not explicitly mention alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'side-effect-free' is consistent. It adds extra context about 'non-archived' and 'active org' filtering, which goes beyond the annotations and helps the agent understand the exact behavioral scope.

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

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

The description is a single, front-loaded sentence with a brief capability note. Every word adds value—no filler or redundancy.

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

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

For a parameterless, read-only list tool, the description fully covers the essential behavioral context: it lists non-archived personas for the active org. Without an output schema, the description sufficiently implies that a list of personas is returned, and the side-effect-free note aligns with annotations.

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 zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies because no parameter information is needed.

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

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

The description uses a specific verb ('List') with a clear resource and scope: 'non-archived AI Presenter personas for the active org.' This distinguishes it from sibling tools like persona_create and persona_status, which clearly have different purposes.

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 use when you need to view existing personas, especially those that are non-archived. However, it does not explicitly name alternatives or state when not to use this tool, leaving some ambiguity compared to other siblings like persona_create or persona_status.

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 states 'CAPABILITY: read — side-effect-free', which restates what annotations already provide via readOnlyHint and destructiveHint. It adds no new behavioral context (e.g., response format, error handling, authorization). No contradiction, but fails to add value beyond structured fields.

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

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

Two concise sentences, front-loaded with the action. Zero waste; every word serves 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 simple one-parameter fetch tool with annotations covering safety, the description is adequate. It states the purpose and side-effect-free nature. The title 'persona status' implies the return is status-related, though the description does not explicitly define the response, which is acceptable given no output schema.

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

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

The single parameter personaId is implicitly described as the id of the persona to fetch. However, since schema description coverage is 0%, the description must compensate but only minimally does so—no format, examples, or additional context are provided.

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 'Fetch one AI Presenter persona by id' uses a specific verb (fetch), identifies the resource (persona), and notes the identifier. This distinguishes it clearly from siblings like persona_list (list all) and persona_create (create).

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

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

The description implies usage: when you need a single persona's details by id. However, it does not explicitly mention alternatives or exclusions, such as using persona_list for multiple personas or persona_create for creation. So guidance is implied, not explicit.

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

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

The description discloses the external PUT operation, no-credential requirement, short-lived URL, need for exact byte size, raw-bytes-only (no base64), and the draft-only capability restriction. These traits go far beyond what annotations (readOnlyHint=false, openWorldHint=true) convey, providing critical operational safety details.

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 with a numbered flow, an example command, and warnings, all in a dense but organized format. Every sentence adds necessary information, from step orchestration to safety caveats.

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 comprehensively covers the multi-step nature, expected return values (key, uploadUrl, publicUrl), the external PUT requirement, expiration risk, and capability implications. No output schema exists, so the description fully compensates by explaining the return contract and sequence.

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 with descriptions (100% coverage). The description adds useful context connecting parameters to the PUT request (e.g., using contentType in the curl header), emphasizing exact size, and showing how parameters fit into the step flow. This slightly exceeds the baseline for high 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 this is the first step of a media upload flow, returning a presigned URL for uploading raw bytes. It explicitly differentiates from upload_media (for tiny files) and finalize_media_upload, making the tool's purpose unmistakable.

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

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

The description provides explicit usage context: use for real image/video, not tiny files; gives the full 3-step flow; warns about URL expiration and recommends one file at a time. It also names the alternative upload_media and the dependent finalize_media_upload.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description redundantly restates this with 'CAPABILITY: read — side-effect-free.' However, it adds meaningful behavioral context beyond the annotations by specifying the scope of the list ('active organization', 'visible system and organization templates plus learned winner evidence') and noting it covers the 'complete inventory.' This informs expected output semantics without contradicting 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 concise: two informative sentences plus a CAPABILITY tag. It front-loads the primary function in the first sentence, adds usage distinction in the second, and the tag provides a safety summary. 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?

For a simple list tool with zero parameters and no output schema, the description is complete. It states what is listed, the scope, the alternative tool, and the non-destructive nature. The sibling context is sufficiently differentiated, and no additional return-format or pagination details are necessary given the tool's simplicity.

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

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

The tool has zero parameters, so the input schema is empty and the description needs to explain no inputs. Per the baseline for 0-parameter tools, the description adequately covers parameter semantics by not requiring anything more; schema coverage is 100% trivially.

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

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

The description clearly states the tool lists the active organization prompt library, specifically including visible system and organization templates and learned winner evidence. It uses a specific verb and resource, and also distinguishes itself from prompt_suggest, making its 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?

The description explicitly contrasts with prompt_suggest: 'Use prompt_suggest for the ranked generation default and this tool to inspect the complete inventory.' This gives clear guidance on when to use this tool versus the alternative, and the 'side-effect-free' note reinforces safe inspection 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?

The description supplements annotations by stating 'CAPABILITY: `read` — side-effect-free,' reinforcing the readOnly and non-destructive hints. It also details the ranking nuance: 'Organization winners rank above source-cited best-practice templates only when confidence is medium or high.' This adds behavioral context beyond the schema and 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 three sentences, front-loaded with the primary action, followed by usage guidance, ranking nuance, and a capability note. Every sentence contributes meaningful information without redundancy, and it is well-structured for quick parsing by an agent.

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 core purpose, usage timing, mapping of kind values, and ranking behavior. It lacks details such as the number of results returned or pagination, but for a suggestion tool with read-only semantics and no output schema, it provides sufficient context for an agent to select and invoke it correctly. Sibling differentiation is implicitly handled via the 'before generating' directive.

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 67%, leaving the required 'kind' parameter without a description. The description compensates by explaining the semantic difference between POST_HOOK and VIDEO. Niche and platform already have schema descriptions, so the tool's description adds value primarily for the kind parameter, but not extensively for the others.

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

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

The description clearly identifies the tool's function: 'Return ranked, evidence-labeled prompt scaffolds for the active organization.' It uses a specific verb (Return) and resource (prompt scaffolds), and the phrase 'Call this before generating any post or short' differentiates it from generation tools like create_drafts and shorts_generate.

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

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

It explicitly states when to call the tool: 'before generating any post or short' and instructs to 'start from the first result.' It also maps the kind parameter to use cases: 'Use POST_HOOK for post openings and VIDEO for short-video structures.' This provides clear usage context, though it doesn't name specific alternative tools, the guidance is direct and actionable.

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 by disclosing that it uses the 'real scheduler/provider pipeline', that records become PUBLISHED only after platform publishing succeeds (async, state transition), and that this 'can reach a LIVE AUDIENCE' (real-world side effect). It also explains permission behavior (draft-scoped token gets 403, human approval needed). This adds significant context beyond the basic readOnly=false, idempotent=false annotations, with 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 concise sentences: first states the action and constraints, second explains the pipeline and state outcome, third warns about permissions and capability. Front-loaded with the primary verb and resource, every sentence adds unique value, no redundancy, within reasonable 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?

For a simple action with one parameter and no output schema, the description covers purpose, usage constraints, behavioral effect, permission requirements, and state transition. It even mentions the real-world impact (live audience). No significant missing context; the absence of return value details is acceptable since this is a command-style action and the success/failure is inherent.

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% (id described as 'Post id'), so baseline is 3. The description adds eligibility semantics: the id must refer to an 'existing draft/scheduled/failed post' and 'must belong to the active org', which is not in the schema. It also implies the id type (string identifier) but reinforces that not all posts are valid targets. Valuable enrichment 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 action: 'Queue an existing draft/scheduled/failed post for immediate publishing on the next scheduler tick'. It names the resource (post), the scope (existing draft/scheduled/failed, active org), and the timing (immediate/next tick), distinguishing it from siblings like schedule_post (future scheduling) and cancel_post. The CAPABILITY warning adds important context about live audience impact.

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 specifies when to use (for any existing draft/scheduled/failed post needing immediate publication) and provides a when-not/alternative: 'A draft-scoped token gets a 403 here; a human must approve at timetopost.co instead.' It implicitly contrasts with scheduling via 'immediate publishing' but does not explicitly name sibling tools like schedule_post or cancel_post. Slight gap in explicit alternative naming, but the guidance 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?

Beyond the annotations (readOnly=false, openWorld, idempotent false), the description adds critical behavioral context: 'CAPABILITY: publish — this can reach a LIVE AUDIENCE,' the token restriction ('A draft-scoped token gets a 403 here; a human must approve at timetopost.co instead'), and the scheduling behavior ('omit to go out on the next scheduler tick (~1 min)'). This significantly enhances what the agent knows about the tool's side effects and limitations.

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

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

The description is long but densely packed with necessary operational details. It is front-loaded with the core purpose and segment structure, then includes behavioral, permission, and style guidance. The writing-style rules are verbose but relevant for an agent that may draft content; still, they could be moved to a linked reference to tighten the tool description.

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 purpose, scheduling, permissions, and follow-up verification via get_post. However, it does not describe the return value/response shape of publish_thread itself, and with no output schema, this leaves an important gap. Agents must assume what the tool returns and rely on get_post to confirm the actual post IDs, which is a notable omission.

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

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

The schema already covers brand and schedule_at descriptions, and the description adds meaning for segments by clarifying that 'segments[0] is the anchor tweet; segments 2..N ... publish as chained replies' and expands schedule_at with 'future ISO datetime; omit to go out on the next scheduler tick.' This fills the gap for the undocumented segments parameter and enhances the schedule_at semantics.

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: 'Publish or schedule an X/Twitter thread in one call.' It further distinguishes itself from siblings by noting it's a 'Convenience wrapper over schedule_post + thread,' and explains the segment structure, leaving no ambiguity about the tool's function.

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 usage context: it positions itself as a wrapper over schedule_post + thread, advises following up with get_post to confirm platform post ids, and instructs reading account recent posts with list_posts before drafting. It does not explicitly contrast with publish_post for single posts, but the wrapper phrasing and thread-specific purpose give adequate guidance.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful context: the irreversible nature ('never be posted'), that the optional reason is stored for later retrieval, and a safety note about being safe for a draft-only agent token. 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 three sentences, each adding distinct value: action/effect, reason storage, and capability/security context. No wasted words, and key details are front-loaded.

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

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

For a simple rejection tool with two parameters and no output schema, the description covers the action, outcome, optional input meaning, and security context. It doesn't detail errors or idempotency, but annotations and the simple domain make it sufficiently complete.

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

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

Schema coverage is 0% in the description. The description gives semantic meaning to the 'reason' parameter (stored for the submitting engine to read back), but 'draft_id' is left to the schema with no added explanation. It partially compensates for the lack of 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 uses a specific verb ('Reject') and resource ('pending or approved draft') and clearly states the effect ('so it can never be posted'). It distinguishes itself from siblings like approve_draft by focusing on rejection and permanent non-posting.

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

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

It implies when to use (for pending or approved drafts that should never be posted) and mentions the reason is read back via list_drafts, giving context. It doesn't explicitly exclude alternatives, but the purpose is clear enough to guide selection among sibling draft-management tools.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description exposes critical behaviors: it discloses that scheduling 'will push it to a live audience', that TikTok values must never be invented or carried over, that an incomplete TikTok block is 'rejected naming the fields still missing', and that in mixed requests only TikTok is refused. It also mentions the 403 on authorization mismatch, adding substantial operational 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 dense and front-loaded, with the core purpose in the first sentence. However, it is quite long and somewhat repetitive (e.g., emphasizing 'from the human' in multiple forms). Each sentence adds value, but a minor trim would improve readability without losing information.

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

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

Platform-specific requirements, style guidelines, and failure modes are thoroughly covered. However, the description does not explain what a successful call returns (no output schema is provided), nor does it mention how mediaUrls relate to the sibling upload tools (prepare_media_upload, upload_media, finalize_media_upload) — leaving some integration ambiguity for an agent.

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%, but the description adds a wealth of meaning: TikTok fields must be human-provided and sourced from get_tiktok_creator_info; Pinterest requires exactly one image URL and maps content to the pin description (≤500 chars) and title (≤100 chars); `brand` is clarified as NOT an AI BrandVoice profile. This significantly enriches what the schema alone 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 opens with 'Create a post. Provide a future ISO scheduledAt to schedule it (omit for a draft).' which clearly states the verb, resource, and the two modes (schedule vs draft). It also distinguishes from siblings by explicitly naming the capability (`draft` vs `publish`) and platform-specific behavior.

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

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

It gives direct prerequisites: 'Call get_tiktok_creator_info first...', 'call list_boards first to get a valid boardId', and 'Before drafting, read the account's recent posts with list_posts'. It also warns against using scheduledAt with a draft-scoped token ('gets a 403') and explains when to omit scheduledAt, providing clear when-to-use and 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 readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description reinforces this with 'side-effect-free' and adds what data the tool exposes (last tick, failures). However, it does not disclose any additional behavioral traits such as rate limits or data freshness, and the added value beyond annotations is limited.

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 very brief with only two sentences. The first sentence delivers the core purpose and content, while the second sentence is somewhat redundant given the annotations but still concise. It is front-loaded and wastes no 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 the tool's simplicity (0 parameters, no output schema), the description provides some context by mentioning 'last tick, failures' as the health indicators. However, it does not specify the exact return format or how failures are represented, which could leave an agent uncertain about parsing the response. A bit more detail would round it out.

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

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

The tool has zero parameters, and the schema reflects this with 100% coverage, so the description does not need to explain parameter semantics. Per rubric, 0 params yields a baseline of 4; the description does not add parameter-specific information, but none is required.

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

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

The description clearly identifies the tool as reporting the health of the background post scheduler, mentioning specific details like last tick and failures. This distinguishes it from sibling tools like schedule_post and cancel_post, which perform actions rather than report status. The implicit verb 'get/check' is clear from context.

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 the tool is used to inspect scheduler health, but does not explicitly state when to use it versus alternative status tools (e.g., shorts_status, build_in_public_status). No exclusions or alternative tool references are provided, so the guidance is minimal.

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 the annotations by explaining the full backend pipeline: grounded script, ElevenLabs voiceover, ShortSpec, object storage, and return values. It also discloses the non-publishing behavior, human-approval requirement, and the draft capability that marks this as safe for draft-only tokens. This adds critical behavioral context about side effects and permissions that annotations alone don't convey.

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

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

The description is long but every section earns its place: a prerequisite, the tool's outcome, source-kind rules, backend behavior, non-publishing note, and a capability classification. It is front-loaded with the most critical instruction (call prompt_suggest first) and structured in clear segments. No redundant 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 the tool's complexity (nested source object, multiple source types, multi-stage backend pipeline), the description covers all necessary aspects: inputs, outputs, behavioral constraints, prerequisites, and safety profile. Since there is no output schema, it specifies the returned fields (draftId/spec/script) explicitly. It also provides the capability tag for access control, making it complete for an agent to select and invoke safely.

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 description compensates for the schema's lack of source-kind enumeration by explicitly listing valid values ('autoseo', 'ship-digest', 'trend', 'template', 'raw') and the required nested fields for each. This is essential for the agent to correctly construct the source object, which is the sole required parameter. The schema already describes other params well, and the description adds the missing source semantics.

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

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

The description clearly identifies the tool's function: generating a PENDING AI Short draft from an existing source for human review. The verb 'Generate', the specific resource 'approval-ready AI Short draft', the PENDING status, and the explicit 'It never publishes' distinguish it from publishing and other creation tools. The description also names the output artifacts (script, voiceover, ShortSpec, draftId) giving full 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 instructs to call prompt_suggest first and base the prompt on the top result, providing a concrete usage prerequisite. It states the tool is Pro-only and allowance-capped, and that the result is a draft that cannot reach an audience, implying it should not be used for direct publishing. It doesn't explicitly name alternative tools, but the 'never publishes' and human-review-rail details provide clear when-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 readOnlyHint, idempotentHint, and destructiveHint. The description adds 'org-scoped' and 'CAPABILITY: read — side-effect-free' along with the conditional render-attachment metadata, providing useful behavioral context 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?

Every sentence contributes: the action, the return fields, and the scope/capability. It is front-loaded with the verb and remains concise while thoroughly describing the return payload.

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

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

For a single-parameter read tool with no output schema, the description enumerates all expected return fields and the conditional MP4 metadata, making behavior predictable. No important gaps for a status-read operation.

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

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

Schema covers 100% of the single parameter with a clear description of draftId. The tool description mentions 'by draftId' but adds no new format or constraint details beyond what the schema already provides, so the baseline of 3 applies.

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

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

Description opens with 'Read the status of one generated AI Short draft by draftId' – a specific verb and resource. It also enumerates the return contents (EngineDraft status, postId, platforms, script, ShortSpec, render attachment metadata), distinguishing it from generation tools like shorts_generate.

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 makes it clear the tool is for reading status of a generated draft, and the schema confirms the draftId comes from shorts_generate. It does not explicitly name alternatives or when-not-to-use, but no other sibling tool serves this exact purpose, so the context is sufficient.

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, the description reveals critical behaviors: base64 encoding overhead (~1.35x size), auto-deletion 30 days after publication, and the 'draft' capability limitation. This adds context not available in the readOnlyHint/destructiveHint flags, helping the agent understand side effects and token 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?

Every sentence carries essential information: purpose, size limit, alternative, platform requirements, deletion policy, and capability. The structure is logical and front-loaded with the core purpose, with no filler.

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

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

For a 3-parameter tool with no output schema, the description covers all aspects needed for selection and invocation: what it does, when to use it, behavioral caveats, and capability scope. It even describes the return type (hosted public URL) despite no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical meaning to dataBase64 by explaining the base64 encoding overhead and size constraints, which guides the agent in populating parameters correctly. It does not deeply explain each parameter but complements the schema effectively.

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 a specific verb+resource: 'Upload a SMALL image/video inline and get a hosted public URL for schedule_post mediaUrls.' It distinguishes itself from sibling tools by explicitly targeting small files and naming prepare_media_upload + finalize_media_upload as the alternative for larger files.

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 versus alternatives: 'Only practical for tiny files... For ANY real photo or video (over ~100KB) use prepare_media_upload + finalize_media_upload instead.' Also adds platform context (Instagram/TikTok require hosted media) and capability context (draft-only).

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 that the tool is side-effect-free and performs a 'read' capability, complementing the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It also reveals the behavioral quirk about draft-only tokens and 403 errors on routes reaching a live audience, which is valuable contextual behavior not evident from annotations alone. 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 compact and front-loaded: sentence 1 states the core purpose, sentence 2 gives usage directive and consequence, sentence 3 states capability and side-effect-free nature. Every sentence earns its place with no repetition 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 zero-parameter, read-only tool with no output schema, the description provides a complete picture: what it returns, when to call it, and why it matters for planning publishing steps. It fully compensates for the lack of an output schema by enumerating the returned components.

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

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

The tool has zero parameters, and the schema descriptions are 100% covered (empty schema). Per the rubric, a baseline of 4 is appropriate for 0-param tools; the description does not and need not add parameter details, though it does enrich understanding of the output.

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 the authenticated user, bound organization, org warning, credential capabilities, and canPublish. It uses a specific verb ('Return') and resource, and distinctively positions itself as the identity/capability introspection tool, setting it apart from siblings like get_capabilities and get_engagement_summary.

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

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

It explicitly instructs 'CALL THIS FIRST' and explains the practical reason: draft-only tokens get 403ed on publish routes, so checking canPublish before planning publishing steps is essential. This provides clear when-to-use guidance and contextual rationale, going beyond mere implied usage.

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