MisarPost MCP Server

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

Adds meaningful context beyond the annotations: it persists/saves the result (consistent with readOnlyHint=false), updates on re-analysis (consistent with idempotentHint=true), and discloses a plan-gated failure path with a specific upgrade message. It does not cover rate limits or handle-resolution failures, but the key behavioral contract is stated.

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

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

Two dense sentences with no filler; the core action and scope lead, and the constraints (plan gating, update-on-re-run) follow. Slightly packed but every clause earns its place.

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

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

With no output schema, the description usefully enumerates the return contents, and it covers the plan-gating failure mode and update semantics. Given four flat parameters and no nested structures, this is nearly complete; only edge cases like invalid handles are unaddressed.

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

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

Schema description coverage is 100%, so all four parameters (handle, platform, niche, display_name) are already documented in the schema. The description adds no syntax, format, or normalization detail beyond what the schema provides, fitting the baseline.

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

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

Starts with a specific verb (analyse) and a precisely scoped resource (a competitor's public X/Twitter or LinkedIn account), then enumerates the outputs produced (posting frequency, content pillars, gaps, engagement, best posting time). This distinguishes it from sibling reads like list_competitor_personas or get_analytics_trends.

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

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

Gives clear context for use: requires a plan that includes competitor analysis, otherwise an upgrade message is returned, and notes that re-analysing the same handle updates the existing record rather than duplicating. No explicit alternative-tool routing is offered, but the when-to-use condition is concrete.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds what those hints do not: the state preconditions that gate cancellation and the fact that cancellation is terminal and cannot be undone by re-queueing. It also adds a user-confirmation requirement, which no annotation conveys.

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 tightly written sentences, front-loading the core action before the constraints, alternative, and confirmation. No sentence is redundant.

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 terminal mutation with no output schema, the description covers scope, preconditions, irreversibility, the sibling alternative, and the confirmation step. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter (post_id) is already documented as a UUID sourced from list_posts. The description adds no parameter-level detail, so the schema bears the burden and 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?

States a specific verb (cancel) and resource (a post), with the exact scope of what qualifies: 'still pending or queued, so it never publishes.' It also names update_post as the sibling for a different intent, letting an agent route without opening other schemas.

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

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

Gives explicit when-to-use (pending or queued), when-not (already publishing or published), the irreversible consequence (cancelled posts cannot be re-queued and must be re-scheduled), the alternative for a different intent (update_post), and a confirmation prerequisite.

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

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

Goes well beyond the annotations (which only flag destructiveHint/idempotentHint) by disclosing that the new config replaces the previous one and that an activated plug later acts on published posts automatically, in public, without re-prompting. That consequence is exactly what an agent needs to reason about before invoking a destructive mutation.

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

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

Three tightly written sentences: action first, consequence/warning second, dependency last. No filler, and the most consequential facts are front-loaded in the first two sentences.

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

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

For a destructive, auto-acting mutation with no output schema, the description covers replacement semantics, public automatic behavior, and where to source valid inputs. It stops short of covering failure modes or confirming whether config is optional, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so the schema already documents account_id, plug_key, activated, and config. The description's only parameter-related content ('get valid plug keys and config fields from list_account_plugs') restates what the schema's own descriptions already say, adding no syntax or format detail beyond 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?

States a specific verb pair (turn on/off and set configuration) plus the exact resource (a plug for one connected account), and clarifies the replace semantics. An agent can distinguish this from list_account_plugs or any other sibling without opening a schema.

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

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

Gives clear prerequisites (get valid keys/fields from list_account_plugs) and a strong usage directive (confirm the exact plug and settings with the user first). It does not name an explicit when-not or a competing tool, but the routing context is solid.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description goes beyond them with genuinely additive facts: analysis runs asynchronously in the background, it consumes the plan's AI image allowance, and it returns a job id to poll. It stops short of stating what happens on re-invocation or partial-failure behavior, so a 4 rather than a 5.

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

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

Two dense sentences with the primary action front-loaded and the cost/polling caveats subordinated in parentheses. The nested "for the persona cover" clause is a slight readability stumble but no sentence is wasted.

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

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

With no output schema, the description correctly supplies the return contract (job id) and the polling path, and annotations cover the safety profile. It is nearly complete; only edge cases like re-running the same persona or failure states are unaddressed, which is low-risk for an async job-start tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the platform/source_kind pairing and the required-for-each-mode notes. The description adds platform-to-mode mapping but nothing about name or identifier limits beyond what the schema already says, so the 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?

States a specific verb+resource ("Start learning a writing persona from recent posts") and immediately disambiguates the two operating modes (connected_account vs public_profile) with their platform sets. An agent can distinguish this from siblings like generate_persona_post or delete_persona without opening the schema.

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

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

Explicitly maps source_kind to allowed platforms (connected_account: instagram/twitter/youtube; public_profile: youtube/medium/mastodon/bluesky), which is the key selection decision, and names the follow-up tool (get_persona_job_status) for polling. Routing is fully specified rather than inferred.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description nonetheless adds a genuinely useful constraint not present in the schema or annotations: names must be unique per user, which warns the agent about duplicate-name failures. It stops short of saying what happens on collision (error vs. auto-rename) or what the response contains.

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

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

A single front-loaded sentence: action, required inputs, then purpose, then constraint. No filler, no repetition of enum values.

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

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

For a two-parameter create tool with full schema coverage and annotations covering safety, the description is nearly complete; the uniqueness rule is the key addition. The only gap is that with no output schema, the description does not say what is returned (e.g. the new tag's id), which would help an agent chain calls.

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% (name length 1-60, color enum of ten values), so the schema carries parameter meaning on its own. The description repeats the two fields in prose and adds only the uniqueness constraint, 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?

States a specific verb+resource ("Create a post tag") and adds the purpose ("for grouping posts by campaign or theme"), which is enough to distinguish it from the sibling verbs update_post_tag, delete_post_tag, and list_post_tags without opening any schema.

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

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

The stated purpose (grouping posts by campaign or theme) implies when a caller would reach for this tool, but there is no explicit when-to-use, no prerequisites, and no routing to the update/delete/list tag siblings. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond those hints: despite being a write, saving publishes nothing. It stops short of covering auth requirements, duplicate-name behavior, or limits.

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, no filler, and the core action plus payload are front-loaded with the important non-publishing caveat last. Every clause earns its place.

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

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

For a create tool with full schema coverage and annotations covering the safety profile, the description is nearly complete; the "publishes nothing" note closes the main behavioral risk. It does not indicate what is returned (e.g. a template ID) despite there being no output schema, which is the only 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?

Schema description coverage is 100%, so the schema already documents every parameter, including nested media objects and platform_settings. The description's prose list (default text, per-platform text, target accounts, settings, media, first comment) largely restates those fields; only "optional per-platform text" mildly clarifies content_overrides. Baseline 3 is correct.

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

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

States a specific verb and resource ("Save a reusable post template") and enumerates the payload it captures, so an agent immediately knows this creates a stored template rather than a post. It does not name a sibling, but the create-vs-update-vs-publish distinction is derivable from the name and the closing clause.

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

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

Usage is only implied. "Saving publishes nothing" tells the agent this is not a publishing action and therefore differs from schedule_post, but there is no explicit when-to-use statement or exclusion relative to update_post_template or create_post_tag. Adequate but with a clear gap.

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 the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely useful context beyond them: 'Saves nothing' clarifies there is no persistence, and 'counts against the monthly AI allowance' discloses a quota cost. Return format is not described, but no output schema exists to cover it either.

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

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

Three tight sentences, front-loaded with the purpose before the behavioral caveats. Every sentence carries distinct information 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 one-parameter generation tool the description covers purpose, cost, persistence behavior, and workflow placement. The only omission is what the returned script looks like, which is minor given no output schema exists.

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 a single parameter at 100% schema description coverage, the schema already defines post_text and its length bound (1–4000 characters). The description adds no extra parameter meaning, so the baseline 3 for schema-covered parameters 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?

States a specific verb (write), a precisely scoped resource (short talking-presenter video script), and the input it derives from (a post's text). An agent can distinguish this from generate_video, which produces the finished video rather than the script.

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 positions the tool in a workflow: 'Show the script to the user before generate_video,' which tells the agent this is a preceding step, not a terminal action. It does not name an explicit when-not-to-use condition, keeping it 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?

Adds substantial behavior beyond the annotations (which only say readOnly=false, openWorld=true, non-idempotent, non-destructive): payloads are signed, the signing secret is returned exactly once and cannot be retrieved again, and the user must approve the URL. These are exactly the operative facts an agent needs to act safely, and nothing contradicts 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?

Three tight sentences, each carrying a distinct piece of load-bearing information (effect, secret handling, approval requirement), with the core action stated first. 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 non-idempotent, open-world mutation tool with no output schema, the description covers the effect, the one-time secret in the response, and the approval prerequisite — everything needed to call it correctly and handle the result.

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

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

Schema coverage is 100%, so both parameters are already documented with max length and the event enum; baseline would be 3. The description goes beyond that by tying the url parameter to the account-data/approval constraint and framing events as 'the chosen events', adding usage meaning not present in the schema.

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

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

States a specific verb+resource ('Register an outbound webhook') and immediately defines the effect: MisarPost will POST signed payloads for the chosen events to this URL going forward. This cleanly separates it from list_webhooks, update_webhook, and delete_webhook without needing to name them.

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

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

Gives a clear precondition for use — 'Sending account data to a new URL needs the user's explicit approval of that URL' — which is real routing guidance for a mutating tool. It does not name an alternative tool or state when not to use it, 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 flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real context beyond that: the deletion is permanent, and posts referencing the URL keep the URL text while the underlying file is destroyed — a non-obvious side effect. Auth requirements and failure modes are still unstated, keeping it from a 5.

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

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

Three short sentences, each carrying distinct load: what happens, the downstream consequence, and the required user confirmation. The destructive action is front-loaded and there is no filler.

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

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

With one required parameter, full schema coverage, no output schema, and rich annotations, the description covers the remaining agent-relevant gaps: permanence, referential side effects, and the confirmation step. Nothing needed to invoke it safely is missing.

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

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

Schema description coverage is 100% and the single media_id parameter is fully documented in the schema, including its source (list_media). The description adds no format or sourcing detail beyond that, 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?

States a specific verb (delete) plus the exact resource (a file from the media library and storage), and the scope word 'permanently' sets it apart from reversible operations. Among the many delete_* siblings, the resource noun alone tells an agent which entity is affected.

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

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

Gives one clear procedural rule — 'Confirm with the user first' — which is genuinely actionable. However, it never states when this is the right tool versus alternatives (e.g. removing a post that references the file, or unlinking rather than deleting), so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description nonetheless adds real value beyond them: it clarifies WHAT is destroyed ('its learned voice') and the cost of reversal ('Recreating it means re-running create_persona'). It omits permission/auth requirements, keeping it short of a 5.

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

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

Three short sentences, no filler. The destructive outcome and permanence are front-loaded, and the confirmation instruction is saved for last where it functions as a final safeguard.

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 destructive tool with no output schema, the description covers the essential agent concerns: what is destroyed, that it is permanent, the recreate path, and the confirmation requirement. Annotations carry the machine-readable safety flags. Only the omission of alternative tools keeps it from being fully complete.

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

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

Schema coverage is 100% and the single parameter's description already points to list_personas for obtaining the UUID. The description does not reference the parameter at all, so it adds nothing beyond the schema — the baseline 3 for full 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?

States a specific verb and resource ('delete a persona'), and adds scope beyond the name: it also removes 'its learned voice.' That scope detail plus the recreate path distinguishes it clearly from siblings like delete_media, delete_post_tag, and rename_persona.

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

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

Gives actionable context — the deletion is permanent and confirmation should be obtained first — which frames when invocation is appropriate. It does not, however, name a non-destructive alternative (e.g., rename_persona) for cases where the user only wants to modify the persona, so it falls short of explicit when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety bar is low. The description still adds value beyond them: permanence/irreversibility, the cascade behavior on posts ('remove it from every post that carries it'), and the explicit reassurance that posts themselves are unaffected. Auth requirements and failure modes are not covered.

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

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

Three short sentences, front-loaded with the destructive action and its blast radius, then the reassurance, then the caution. 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 one-parameter destructive delete with full annotation coverage and no output schema, the description supplies what an agent needs: irreversibility, scope of effect, and a confirm-first directive. Only error/not-found handling and recovery paths are left unstated, which is a minor gap.

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

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

Schema coverage is 100% with a single tag_id parameter whose schema description even points back to list_post_tags. The description adds no format, sourcing, or lookup guidance beyond what the schema already provides, so the 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?

States a specific verb (delete) and resource (post tag) plus the side effect of detaching it from every post. This clearly separates it from delete_post_template, delete_media, and update_post_tag in the sibling list.

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

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

The instruction 'Confirm with the user first' is a real usage directive and signals this is irreversible, but there is no guidance on when to delete vs. rename (update_post_tag) or how to recover a removed tag. Usage is implied via the destructive framing rather than explicitly contrasted 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so safety profile is covered. The description adds genuinely new behavioral context: the deletion is permanent and already-scheduled posts originating from the template survive, which is exactly the blast-radius information an agent needs before a destructive call.

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

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

Three short sentences, no filler, with the destructive action front-loaded and the consequence and user-confirmation caveat following in priority order. Every sentence earns its place.

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

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

For an irreversible single-parameter delete with no output schema, the description covers permanence, side-effect scope, and the confirmation requirement — enough to call it correctly. It stops short of stating authorization requirements or recovery options if the template is deleted in error.

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

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

There is only one parameter and schema description coverage is 100%; the schema itself explains template_id is a UUID sourced from list_post_templates. The description adds no format, ID-discovery, or naming semantics beyond that, so the 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?

Names a specific verb (delete) and resource (saved post template), with the adverb 'permanently' pinning down the operation's semantics. The resource name cleanly separates it from siblings like delete_post_tag, delete_persona, and delete_media without needing the schema.

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

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

Gives one real usage instruction — 'Confirm with the user first' — which tells the agent to gate the call on user approval. However, it never names alternatives (e.g., update_post_template to modify rather than remove) or states prerequisites such as ownership or permissions.

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

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

Goes well beyond the annotations by disclosing a non-obvious non-cascade rule: posts already scheduled or published are left untouched. It also states irreversibility in plain language, complementing destructiveHint=true with the practical consequence an agent needs to reason about.

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

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

Three short sentences, each earning its place: what gets deleted, what is spared, and the safety precondition. The destructive warning is front-loaded at the end where it lands hardest, 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 single-parameter destructive tool with no output schema, the description covers the operation, its boundary conditions, and its irreversibility. Nothing an agent needs to call it correctly is missing.

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

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

The single parameter is fully documented in the schema (100% coverage), including that the UUID comes from list_repurpose_history. The description adds only the implication that exactly one source is deleted per call, 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?

States a precise verb and resource ('Delete one repurposed source and its variants') with an explicit scope ('from ContentRipple history'). An agent can distinguish this from delete_media, delete_persona, and delete_post_template without opening a schema.

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

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

Provides a directive ('confirm with the user first') which guides invocation, but never states when to reach for this tool versus alternatives like cancel_post or revert_post. Usage is implied by the name and description rather than explicitly framed.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds value beyond them by stating the permanence and the concrete effect (event delivery ceases), which clarifies what is actually destroyed. It still does not say whether the deletion can be undone or what auth/scope is required.

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

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

Two short clauses with the destructive scope front-loaded and the safety instruction trailing; every word earns its place with no filler.

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

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

For a single-parameter destructive tool with no output schema, the description covers purpose, consequence, and the required confirmation step. Nothing an agent needs in order to call it safely is missing.

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

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

Only one parameter, and the schema already documents it fully at 100% coverage, including its source ('from list_webhooks'). The description adds no syntax or format detail beyond that, 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?

States a specific verb and resource ('Permanently remove an outbound webhook') plus the operational consequence ('events stop being delivered to its URL'). The word 'permanently' implicitly distinguishes it from update_webhook, which modifies rather than removes.

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

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

Gives an explicit precondition ('Confirm with the user first'), which is exactly the kind of guidance a destructive tool needs. It does not, however, name an alternative such as update_webhook for merely disabling delivery, so the agent gets a caution but no routing rule.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the mutation/external-call profile is partly covered. The description adds genuinely new behavioral context: it persists nothing and consumes the monthly AI allowance, which is a cost/quota trait no annotation conveys.

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

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

Two tight sentences, front-loaded with the transformation and followed by the operational caveats and downstream routing. No filler and every clause carries 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?

There is no output schema, and the description compensates by enumerating what the brief contains (sharper topic, tone, angles, key messages), while also covering cost and next-step usage. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (including the goal enum and platform list) are already documented in the schema. The description only alludes to 'the chosen platforms' and adds no format or syntax meaning beyond that, so the 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?

Specific verb ('Rewrite') plus resource ('raw topic or idea') plus the concrete output ('structured content brief: a sharper topic, suggested tone, content angles and key messages'). It also situates the tool in the workflow by naming generate_plan/generate_posts as downstream consumers, so an agent can distinguish it from those siblings.

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

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

'Feed the result to generate_plan or generate_posts' gives clear context for when to call it (as an upstream step before generation) and the cost caution signals it should not be called gratuitously. However, it names no explicit alternative for the same job and states no when-not condition.

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 openWorldHint=true and idempotentHint=true, so external network fetching and repeatability are covered structurally. The description adds one useful behavioral fact ('Nothing is saved'), but says nothing about auth needs, rate limits, or fetch failure behavior. Note the mild tension: 'Nothing is saved' reads as a no-side-effect claim while readOnlyHint=false implies the operation is not read-only; this is more likely a loose annotation than a description error, so it is not flagged as a contradiction.

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

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

One sentence, front-loaded with the action, followed by the downstream purpose and the no-save guarantee. No filler.

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

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

No output schema exists, so the description carries some return-value burden, and it does state that entries are returned. For a one-parameter fetch tool with annotations covering safety/idempotency, this is close to complete; entry format details are the only minor gap.

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

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

Single parameter with 100% schema description coverage, so the schema already defines feed_url as the RSS/Atom feed URL. The description adds no syntax or format detail beyond that; 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?

Specific verb+resource: reads an RSS/Atom feed and returns its entries. It also distinguishes itself from the large sibling set by routing to the downstream tool repurpose_content (source_type rss), so an agent can place it in the workflow immediately.

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?

States the purpose-driven context ('so the user can pick one to repurpose') and names the follow-up tool explicitly. There is no explicit when-not-to-use or alternative feed source, but the intended usage is unambiguous.

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 readOnlyHint=false, the agent knows a write occurs, but the description usefully clarifies that the write is internal ('save them as a bio A/B test') and that 'Nothing is changed on the platform itself' — a non-obvious scope boundary. It also discloses the cost profile ('Uses one AI text action'). It stops short of noting that the call is non-idempotent, i.e. that repeated invocations create additional A/B tests.

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 action and output shape, followed by the two facts an agent can't get from structured fields: AI-action cost and platform-side safety. No filler or restated title.

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

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

For a 2-parameter tool with no output schema, the description covers what is produced, where it is stored, and its side-effect boundary. It leaves implicit that a trained voice model is a prerequisite (implied by 'in the user's trained voice') and how the resulting A/B test is later retrieved or evaluated, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented there, including that current_bio is 'the bio the user has now, to improve on.' The description adds only that current_bio is optional, which the schema already conveys via the required list. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Generate two profile-bio variants for one platform') plus the distinguishing output ('save them as a bio A/B test'), which separates it from siblings like generate_persona_post or generate_posts. The A/B framing and the A-authority / B-curiosity split tell an agent exactly what comes back.

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

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

It gives a conditional for the optional parameter ('Optionally pass the current bio to improve on'), which is useful, but offers no when-to-use guidance relative to siblings such as generate_persona_post, generate_posts, or train_voice_model. Usage must be inferred from the name and the description's scope.

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

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

Adds real behavioral context beyond annotations: the result is persisted to the user's media library, the URL is returned for attachment, and it consumes one AI image action from the plan quota. Annotations already declare non-readonly, non-destructive, open-world, non-idempotent. The remaining gap is auth/pricing edge cases and whether generation is synchronous, which the direct URL-return phrasing implies but never states.

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 core action and output are front-loaded, with the platform-sizing parenthetical and the quota/non-posting caveats following in order of usefulness. No sentence is redundant with the name or schema.

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

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

With no output schema, the description supplies the return value (a media URL to attach to a post) and the side effect (stored in media, nothing published). Nothing an agent needs to call it correctly is missing for a two-parameter generation 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%, so baseline is 3, but the description adds semantic mapping the schema lacks: the platform enum expands to concrete aspect ratios (16:9 for X/LinkedIn/YouTube, square for Instagram/Threads, 9:16 for TikTok), telling the agent exactly what the parameter controls. The prompt parameter's length bounds are left to 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?

States a specific verb and resource ('Generate an image for a post from a text prompt') plus scope (platform-sized, stored in user's media). An agent can distinguish it immediately from generate_video, generate_posts, and generate_persona_post without opening schemas.

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

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

Gives clear context: it is for post imagery, sized per platform, and explicitly 'Nothing is posted', which scopes it away from publish/schedule tools. It stops short of naming an alternative (e.g. generate_video) or stating when-not to use it, so it is clear context without explicit routing.

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

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

Annotations only cover the safety profile (write, non-idempotent, non-destructive, open-world). The description adds genuinely new behavioral facts: the output is a reviewable draft, not a scheduled post, it returns a voice-match score, and it consumes the monthly PersonaForge post allowance — the quota disclosure is especially valuable for a metered write.

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

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

Two tight sentences, with the core action (write a post in a persona's voice) front-loaded and the caveats (review-only, quota) trailing. 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?

With no output schema, the description usefully mentions the voice-match score return and the review-queue behavior. For a three-parameter write tool it covers the essentials, though it could note whether the persona must exist or how the result is later located (e.g., list_drafts).

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the persona_id 'omit to use own voice' behavior that the description repeats. The description adds no format, range, or validation detail beyond the schema, so the 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?

States a specific verb and resource — write a post in a persona's voice — and clarifies the persona-less fallback (the user's own trained voice). It is easy to separate from generate_persona_reply and generate_posts, though it never names those siblings explicitly.

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

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

"The post is saved for review, not scheduled" tells the agent when this tool is the right choice versus a scheduling tool like schedule_post, and the persona_id omission rule gives clear usage context. It stops short of naming alternatives or stating prerequisites such as needing an existing persona.

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 mark this as a non-readOnly, non-destructive, non-idempotent, open-world write. The description adds genuinely useful context beyond that: the output is only a pending draft and 'nothing is sent,' plus the plan prerequisite. It doesn't cover rate limits or auth scoping, keeping it below a 5.

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

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

Three tight sentences, front-loaded with the action and immediately followed by the critical safety fact that nothing is sent. Zero filler.

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

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

With no output schema, the description correctly explains the outcome (a draft saved as pending) and where to find it, and states the plan requirement. Minor gap: no indication of what the call returns (e.g., a draft id) for follow-up calls.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description implies voice/inbound-source semantics but adds no syntax, format, or length guidance beyond what the schema states, so the 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?

States a specific verb (draft), resource (a reply), and scope (in the user's trained voice, to an inbound comment/message on one of their posts). This clearly separates it from generate_persona_post and from reply_to_post, which presumably sends rather than drafts.

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

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

Gives a hard prerequisite ('Needs a plan with PersonaForge replies') and routes the review step to list_persona_replies. It does not explicitly say when to prefer this over the sibling reply_to_post, 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, but the description adds the reason the tool is not read-only: it 'counts against the monthly AI allowance,' which is important cost/billing context an agent would not get from structured fields. It also explicitly states the absence of side effects ('saves nothing and schedules nothing'), which prevents an agent from assuming a plan is persisted. Non-idempotency and the external AI call are not spelled out, but the annotation already flags openWorld.

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, fully front-loaded: the first states purpose and outputs, the second states side-effect status and cost. No filler, no repetition of the title, and each clause carries distinct information.

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

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

With no output schema, the description partially compensates by enumerating the return contents (hooks, time slots, hashtags per platform). For a two-parameter, non-destructive generation tool with annotations covering openness and safety, this is nearly complete; it does not describe the structure or per-platform grouping of the result, which is the only remaining gap.

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

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

Schema description coverage is 100% for both parameters (enhanced_topic with a 3–1000 char range and a reference to enhance_topic, platforms with an enum and minItems), so the schema carries the semantics. The description only restates 'a topic or brief' and 'per platform' without adding format, length, or platform-specific constraints, which matches the baseline 3 when the schema does the heavy lifting.

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

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

The description names a concrete verb ('suggest') and enumerates the concrete outputs (hook options, best posting time slots, trending hashtags, per platform), so an agent knows exactly what it produces. It also distinguishes itself from scheduling siblings by stating it 'saves nothing and schedules nothing.' It does not, however, differentiate itself from other ideation siblings such as get_trend_hooks or research_hashtags, which overlap on hooks and hashtags.

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?

'For a topic or brief' states the input condition for using the tool, and the clause 'saves nothing and schedules nothing' implicitly scopes it away from any persistence/publishing workflow. There is no explicit 'use X instead' routing to a named sibling, so the guidance is clear but not fully comparative.

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

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

Beyond the annotations (which already mark this as a non-idempotent, non-destructive, open-world write), the description adds real behavioral context: output is draft-only, nothing is scheduled or published, and each call consumes the plan's monthly AI generation allowance. The quota/rate-limit disclosure is genuinely useful and not derivable from 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 tightly packed sentences: the core action and scope lead, the draft-only guarantee and the quota caveat follow. No filler and nothing important is buried.

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

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

With no output schema, the description still tells the agent what is produced (draft variants), where to find them (list_drafts), and the cost implication (generation allowance). That is sufficient for correct invocation, though it stops short of noting what the response returns per variant.

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

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

Schema description coverage is 100%, so topic, tone, count, and platforms are all already documented with defaults and ranges. The description reinforces the count cap ('up to 5 per platform') and the multi-platform nature but adds no syntax or format detail beyond the schema, so the 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?

States a specific verb and resource ('Write AI post variants about a topic') plus the exact scope ('up to 5 per platform', 'one or more platforms') and the artifact produced (drafts). It also names where the result surfaces ('visible in list_drafts'), letting an agent separate it from generate_persona_post and generate_bio_variants without opening any schema.

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

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

Clearly frames the outcome as draft generation and explicitly rules out scheduling/publishing, which routes the agent away from schedule_post. It does not, however, contrast against sibling generators like generate_persona_post or generate_trend_platform_content, so the when-to-use-this-generator-vs-that-one decision is left implicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds real behavioral value beyond that: regenerating REPLACES earlier content for the named platforms (a lossy overwrite that destructiveHint=false alone would not imply) and clarifies nothing is published.

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

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

Three tight sentences: what is generated, what happens on regeneration, and what the output is not. The overwrite constraint and the not-posted caveat are front-loaded and every sentence earns its place.

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

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

No output schema exists, but the description states what is produced (hashtags and titles where a platform needs them) and the overwrite behavior, which is the key thing an agent needs to know before regenerating. Coverage is nearly complete; only the return shape (e.g., per-platform result structure) is left unspecified.

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

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

Schema description coverage is 100%, so both parameters (snapshot_id source 'from get_trends' and the platforms array with 'Omit for all of them') are already documented in the schema. The description's mention of the all-seven default and per-platform hashtag/title output adds only marginal meaning over the structured fields.

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

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

Specific verb (Generate) plus resource (per-platform content: hashtags and titles) scoped to one trend snapshot, and it clearly distinguishes itself from the sibling get_trend_platform_content (retrieval) and use_trend_platform_content (turning into a draft). An agent can identify the tool's role without opening the schema.

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

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

Gives clear context: default is all seven platforms when 'platforms' is omitted, regenerating overwrites prior content for those platforms, and nothing is posted — pointing to use_trend_platform_content as the explicit follow-up for drafting. It does not explicitly contrast with get_trend_platform_content for reading existing content, but the routing guidance is otherwise strong.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely new context: it returns a job id immediately (async, not synchronous), rendering is metered, and it spends the user's video allowance. These behavioral traits are not derivable from the annotations, and the cost warning is especially useful.

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

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

Three tight sentences that are front-loaded with the action, then the return/poll behavior, then the cost caveat. No filler and every sentence carries necessary information.

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

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

With no output schema, the description fills the gap by explaining it returns a job id and how to poll for completion, plus the cost implication. An agent has everything needed to invoke it correctly and handle the result.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including defaults and the enum. The description merely restates 'script, avatar and voice' without adding format or syntax detail, so the 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 a specific verb and resource ('Start rendering an AI presenter video') and names the three key inputs (script, avatar, voice). This clearly distinguishes it from siblings like generate_image or create_video_script without needing to compare schemas.

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

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

It names the follow-up tool explicitly ('poll get_video_status until it completes') and gives a prerequisite ('confirm the script first'). It doesn't compare against alternatives like create_video_script, but the when-to-use and next-step 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?

Annotations already declare readOnly/idempotent/no-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: each channel's metric field distinguishes real engagement data from publish-volume-only channels, with an explicit warning not to present a posts-only channel's zero engagement as a real result.

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

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

Front-loaded with the what/scope in the first sentence, then a focused caveat about interpreting the metric field. Two sentences, no padding, each carrying load.

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

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

There is no output schema, so the description must characterize return values, and it does: daily per-channel metrics plus change vs. the previous period. Combined with the metric-field caveat, an agent has enough to call and interpret it, though it lacks any note on absent/history limitations.

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

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

Schema coverage is 100% and the single 'days' parameter already documents its enum and default in the schema. The description mentions the same 7/30/90 windows but adds no format or semantics beyond the structured field, 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?

States a specific verb (Get) and resource (per-channel daily trends) and enumerates what is returned: posts published/failed, engagement, impressions, totals, and period-over-period change. It is clear on its own, but it never names or contrasts with overlapping siblings like get_stats, get_growth_overview, or get_trend_performance, so an agent must infer the boundary.

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

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

The 7/30/90-day framing implies it is for windowed trend analysis, but there is no explicit when-to-use, when-not, or alternative-selection guidance. With several adjacent analytics tools (get_stats, get_growth_overview, get_trend_performance), leaving routing to inference is a real gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety bar is low. The description adds genuinely useful context beyond that: default date window, oldest-first ordering, the full set of returned fields, and the plan-gated upgrade-message failure mode.

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

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

Two dense but well-ordered sentences, front-loaded with the core action and date window, then tacked-on filtering and the plan caveat. Nearly every clause carries information, though the returned-field list makes it slightly heavy.

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, fully-schematized list tool with annotations covering safety and no output schema, the description is nearly complete: it discloses the default range, ordering, field payload, optional filter, and the upgrade-gated failure mode. Only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so from/to defaults and the tag_id UUID are already documented and the baseline is 3. The description restates the date defaults and clarifies tag_id filters to posts carrying one tag, adding marginal meaning over the schema without new syntax or format detail.

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

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

The description gives a specific verb ('Get') and resource ('every post scheduled between two dates'), plus scope, ordering, and returned fields. The phrase 'the content calendar view' frames it distinctly from the bulk listing siblings like list_posts, though no sibling is named explicitly to confirm the boundary.

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

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

'Needs a plan that includes the content calendar; otherwise it returns an upgrade message' is a useful prerequisite, and the default window is stated. However, it never says when to reach for this over list_posts, fetch_content_feed, or list_drafts, so routing between calendar and listing tools is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds the "null means unlimited" semantics and the reason for checking, but does not cover quota reset timing or what happens when the limit is reached — modest added value against an already-informative annotation set.

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 zero waste: the first front-loads what is returned, the second supplies the usage trigger. 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 no output schema, the description carries the return-value burden and does so fully — count this month, limit with null meaning unlimited, and plan tier. Enough for an agent to call and interpret it correctly without further information.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description appropriately spends no words on inputs.

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

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

States a specific verb (Show) and precisely enumerates the resource contents: repurpose count this month, monthly limit, and plan tier. The purpose is unmistakable and cannot be confused with mutation or history-list siblings, though it never explicitly references a sibling it is distinct from.

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?

"Check before a large repurposing run so it does not stop halfway" gives clear, actionable when-to-use context tied to the repurpose_content workflow. It lacks explicit when-not guidance, but the positive trigger is well-specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: the Empire-plan gating and the fallback behavior (returns an upgrade message on other plans), which an agent needs to interpret a non-data response.

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

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

Front-loaded with the purpose and scope, and the plan caveat is placed last. It is a single dense sentence plus a short caveat, efficient overall, though the content enumeration is somewhat packed.

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

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

With no output schema, the description carries the burden of explaining what is returned, and it does so explicitly (trend lines, bottlenecks, best formats, platforms with data). Combined with the plan-gating note, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, with the enum values (7/30/90) and default 30 already documented in the schema. The description repeats the valid windows but adds no new format or semantics beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource (get the Growth Hub overview) and enumerates the exact content returned: per-platform engagement trend lines, weakest platforms, best-performing formats, and platforms with real trend data. This content profile cleanly separates it from siblings like get_analytics_trends and get_stats, which cover different scopes.

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

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

It gives a clear prerequisite (requires the Empire plan; otherwise returns an upgrade message), which is genuinely useful context. However, it never says when to choose this over get_analytics_trends, get_optimization_insights, or get_trend_performance, so alternative selection is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: it returns `{ opportunity: null }` instead of fabricating a result when there is no real signal, and it requires the Empire plan, returning an upgrade message otherwise. These are exactly the failure-mode and auth-gating details an agent cannot get from 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?

Three short sentences, front-loaded with the core purpose before the sibling comparison, return-shape caveat, and plan gate. Every sentence carries distinct information 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?

With no output schema, the description compensates by describing the return shape (including the null case) and the plan-gating failure mode. For a zero-parameter read tool, nothing an agent needs to call or interpret it is missing.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric; there are no arguments whose semantics the description would need to clarify. The description correctly says nothing about inputs rather than padding 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?

States a specific verb+resource ('get the single best next content opportunity') and scopes it to connected platforms and niches. It explicitly positions itself against sibling list_growth_opportunities as 'a compact version', so an agent can tell the two apart without opening schemas.

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

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

The 'compact version of list_growth_opportunities' framing gives clear context for when this one-item tool is appropriate versus the full list tool. It does not state an explicit when-not condition or eligibility prerequisites beyond plan gating, 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 disclose readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds genuinely useful non-obvious context beyond that: the 30-day analysis window and, critically, that each call counts against the monthly AI allowance. The phrase 'Changes nothing' reads as 'no content mutation' and is reconciled by the quota-cost disclosure, so it is not a contradiction of readOnlyHint=false. It does not describe return format or rate-limit behavior, hence a 4.

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

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

Two tightly written sentences: the first front-loads what it analyses and returns, the second delivers the key behavioral caveat. 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?

With no output schema, the description helpfully enumerates the returned insight types, states the analysis window, and flags the AI-allowance cost. It is nearly complete for a single-parameter analysis tool; only explicit differentiation from sibling analytics tools is missing.

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

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

There is a single optional platform parameter whose enum and 'Omit for all platforms' semantics are fully documented in the schema (100% coverage). The description adds no parameter detail, so the schema carries the burden and 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?

States a specific verb (Analyse), resource (last 30 days of post metrics) and enumerates concrete outputs (best time of day, best tone, top hashtags, prompt suggestions, per-platform insights). It is clearly distinguishable from generic siblings like get_stats or get_analytics_trends by its optimization framing, though it never names those siblings explicitly.

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

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

Usage is implied by the output list (you call it to learn optimal posting time/tone/hashtags), and the closing clause warns that each call consumes the monthly AI allowance, which nudges the agent to call sparingly. However, there is no explicit when-to-use vs alternatives guidance and no stated conditions for choosing this over get_analytics_trends or get_growth_overview.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds content-level behavior by listing the fields returned (name, cover image, source account, style profile), which is useful beyond the structured annotations. It does not cover error or permission behavior.

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

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

One sentence, front-loaded with the verb and resource, then the field list. Every clause earns its place; 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 simple read-one tool with complete annotations and a fully documented single parameter, the description is nearly complete. It names the returned fields despite no output schema, though it omits behavior for invalid or missing IDs.

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%; persona_id is fully documented in the schema as a UUID from list_personas. The description adds no syntax or format detail beyond what the schema provides, so the 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?

States a specific verb ('Get') and resource ('one persona'), then enumerates the returned fields, clearly distinguishing it from bulk tools like list_personas. The phrase 'in full' signals a detailed single-record fetch.

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?

Encourages use by requiring a single persona_id and saying 'Get one persona,' but gives no explicit when-to-use guidance or mention of alternatives such as list_personas. The agent can infer it is for fetching a known persona, yet no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return payload's three possible shapes: status, the resulting persona id, or an error. No gaps, but nothing about polling cadence or terminal states either.

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

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

A single sentence with zero filler, front-loading the action and its provenance before enumerating outcomes. Nothing to trim.

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

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

With no output schema, the description takes on the return-value burden and discharges it by listing the possible results (status, persona id, error). For a simple status-polling tool with one fully documented parameter, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, so the schema carries the semantics. The description's only extra hint is the provenance of job_id, which the schema property already states verbatim ('Job id — from create_persona'). 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?

States a specific verb (Check) and resource (persona extraction job), ties it to the originating create_persona call, and enumerates the outcomes it surfaces. An agent can distinguish it from get_persona (direct fetch) and get_video_status (video jobs) without opening a schema.

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

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

Clearly anchors usage to jobs 'started by create_persona', which is the essential trigger condition. It does not name an alternative (e.g. get_persona once the id exists) or state when not to use it, so it stops short of full routing 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 readOnly, idempotent, non-destructive, and closed-world behavior. The description adds that the call returns the template 'in full' including text, accounts, and settings, but does not cover auth, error behavior, or rate limits.

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?

Single sentence, front-loaded with the verb and resource, followed by scope and purpose. Every clause earns its place.

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

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

For a simple one-parameter read with rich annotations and no output schema, the description is complete: it covers what is returned, how to identify the resource, and the intended downstream 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 a single parameter at 100% schema description coverage, the schema already documents template_id as a UUID from list_post_templates. The description's 'by id' adds no syntax or format detail beyond that baseline.

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

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

States a specific verb (get), resource (saved post template), and scope (one, in full, by id), distinguishing it from list_post_templates and the create/update/delete siblings. It also names the downstream use in 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 a clear when-to-use context: reusing the template's text, accounts, and settings in schedule_post. It does not explicitly name list_post_templates as the way to discover IDs or state when not to use it, but the context is unambiguous.

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

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

Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real behavioral context by enumerating the returned sections and disclosing an edge case ('average engagement rate (null when no metrics exist yet)'), which tells the agent how to interpret an empty-metrics account.

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

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

A single front-loaded sentence that opens with the action and resource, then spends its remaining words on concrete return contents. Every clause carries information and nothing is padding.

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 is the agent's only source for return shape, and it discharges that burden by enumerating each metric group. It is largely complete, with only the sibling-overlap question left unaddressed.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. The description adds nothing parameter-related because there is nothing to add, and it does not mislead about inputs.

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

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

The description gives a specific verb and resource ('Get the account overview') and then enumerates exactly what the overview contains, so an agent knows precisely what comes back. It does not, however, distinguish this tool from siblings like get_growth_overview or get_analytics_trends, which also sound like overview/aggregate reads.

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

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

Usage is only implied: the enumerated contents suggest this is the per-account dashboard snapshot to call when you want a broad summary. There is no explicit statement of when to prefer it over get_growth_overview, get_analytics_trends, or the various list_* siblings, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that the result is scoped to a single snapshot and consists of opening lines/angles, but says nothing about volume, pagination, or availability per snapshot.

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

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

A single clause-pair sentence with the action, the resource, and the dependency all front-loaded; nothing is padded or repeated.

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

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

For a one-parameter, annotation-covered read tool with no output schema, the description conveys enough to invoke correctly (what it returns, which snapshot, where the id comes from). Only minor gaps remain around result shape and how many hooks to expect.

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 snapshot_id parameter, and the schema itself already says 'from get_trends'. The description's note about the id source duplicates rather than extends the schema, so the 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?

States a specific verb and resource ('Get the content hooks') and immediately defines what a hook is ('opening lines and angles'), scoped to 'one trend snapshot'. The resource is distinct from siblings like get_trends and get_trend_platform_content, though it doesn't explicitly name what it is not.

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 sequencing prerequisite by noting 'snapshot ids come from get_trends', which tells the agent this tool runs after get_trends. However, there is no guidance on when to prefer this over get_trend_performance or get_trend_platform_content for the same snapshot, and no stated exclusions.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the lower bar applies, and the description still adds real behavioral value: the dataset is bounded to the last 100 TrendPulse drafts and is a pre-joined view of scheduling/publishing outcome plus metric fields. It does not say whether unscheduled drafts are included or anything about result size/ordering.

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

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

One front-loaded sentence with the joining logic stated up front and the metric list trailing. It is dense but each clause carries information, especially the metric enumeration, which stands in for the missing output schema. Slightly run-on, but nothing 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 usefully enumerates the returned measures (likes, comments, reposts, impressions, reach) plus the record scope, and annotations cover the safety profile. Remaining gaps are minor: no time window, no statement about draft ordering or whether drafts with zero performance are included.

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

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

The tool takes no parameters (0 params, 100% schema coverage on an empty schema), so the baseline is 4. There is nothing for the description to disambiguate; the 'last 100' scope is fixed rather than parameterized.

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

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

States a specific verb and resource: shows how trend-sourced posts performed, defined as TrendPulse drafts joined with their scheduling/publishing status and engagement metrics. This is clearly distinguishable from generation siblings like generate_trend_platform_content or queue_trend_drafts, but it never explicitly contrasts itself with the closer analytics siblings (get_analytics_trends, get_stats).

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 usage context is implied — you call it to review the real-world performance of posts sourced from trends. There is no explicit when-to-use or when-not, and no mention of why an agent would pick this over get_analytics_trends or get_stats, which are the obvious nearby 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 this a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: the result is empty until a separate generation step has run, which prevents the agent from misreading an empty response as an error.

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

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

Two sentences, both front-loaded and information-dense: the first defines scope and payload, the second the dependency. No filler.

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

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

No output schema exists, yet the description compensates by enumerating the returned fields per platform. Combined with the prerequisite note and full parameter documentation, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single snapshot_id parameter is fully documented in the schema (including its provenance, 'from get_trends'). The description's phrase 'for one trend snapshot' reinforces but does not extend that meaning, so the 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?

States a specific verb (Get) and resource (per-platform content for one trend snapshot), then enumerates the actual payload: hashtags, YouTube title/description, Medium title/subtitle. It is clearly distinguishable from the sibling generate_trend_platform_content, which produces rather than retrieves this content.

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

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

Names the sibling generate_trend_platform_content and states the condition under which output exists ('Empty until ... has run for it'), which routes the agent to the generator first. It does not, however, contrast against use_trend_platform_content or state when-not-to-use explicitly.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: a two-hour cache window with live refresh fallback, and that results include snapshot ids. It stops short of describing failures or rate limits, keeping it a strong 4 rather than 5.

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

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

Two sentences with no waste; the core purpose is front-loaded and the caching/refresh detail follows. Every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does so partially by naming the returned artifacts (hashtags, hooks, snapshot id). For a zero-parameter read tool with rich annotations this is nearly complete, though it could clarify the relationship to refresh_trends and get_trend_hooks.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and no parameter semantics for the description to add. The 0-param baseline of 4 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?

States a specific verb (get) and resource (trending hashtags and content hooks) scoped to the user's TrendPulse niches, and notes each result carries a snapshot id. It does not, however, distinguish itself from nearby siblings like get_trend_hooks, get_analytics_trends, or refresh_trends, so an agent cannot fully tell them apart from the description alone.

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

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

The mention of returning cached results under two hours old versus refreshing live implies this is the go-to read that tolerates freshness, hinting at how it differs from refresh_trends. But there is no explicit when-to-use or when-not-to-use statement, and no sibling is named, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the three terminal/non-terminal states, that failures carry the error, and that completion yields a URL in media storage. It stops short of guidance on polling cadence or how long processing typically takes.

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

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

A single sentence that front-loads the verb and resource, then stacks the outcome states in order. No filler, no restating the name.

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

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

With no output schema, the description carries the return-value burden and does so by naming all three states and what each contains, plus the downstream handoff to schedule_post. Only a polling/retry expectation is missing, which is a minor gap for a status-check 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?

Only one parameter exists and schema coverage is 100% — the schema already documents job_id including its origin ('from generate_video'). The description repeats the same provenance ('generate_video') without adding format, length, or validity details, 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?

States a specific verb and resource ('Check an AI video job') and enumerates the three possible outcomes: processing, failed with error, or completed with the video URL. The scoping to video jobs (via 'AI video job' and job_id 'from generate_video') distinguishes it from the sibling get_persona_job_status, which serves persona jobs.

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 places the tool in a workflow chain: its job_id originates from generate_video and its completed output feeds schedule_post's media_urls, which tells the agent when to reach for it. It does not state explicit exclusions or how this differs from other status-checking siblings beyond the implicit video/persona split.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the empty-state condition where `model` is null until training has run, which is not derivable from schema or 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 operation and resource, then a dense but relevant enumeration of the returned model fields. Nothing is redundant or padding.

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

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

There is no output schema, so the description carries the burden of describing return values, which it does by listing the model's components. Combined with the empty-state note, an agent has everything needed to call this zero-parameter read correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema coverage is 100% but empty, and no parameter explanation 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?

States a specific verb and resource ('Get the user's own trained voice model') and then enumerates exactly what the model contains (tone breakdown, signature phrases, emoji patterns, etc.). This cleanly separates it from the sibling train_voice_model, which produces the model rather than fetching it.

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

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

The clause '`model` is null until train_voice_model has run' implies a precondition and names the sibling that must run first, which is useful. However, it never explicitly states when to call this tool versus alternatives, nor what to do when the model is null, so guidance is implied rather than stated.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, so the safety burden is covered. The description adds real behavioral context beyond them: it discloses the return composition and specifically that only the 20 most recent plug runs are returned, which is a meaningful scope limit.

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

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

One sentence, front-loaded with the resource and its inline definition, then the return contents. It is dense but every clause carries information; no filler. Slightly long, which keeps it from a 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?

With no output schema, the description correctly carries the burden of explaining returns (configuration, activation, 20 most recent runs) and defines the domain term 'plugs'. Nothing essential for calling it correctly is missing, though platform scope could be clearer as a filter.

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

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

Schema coverage is 100% with the single account_id parameter documented (including its source, list_connections). The description reinforces that the scope is one connected account but adds no new syntax or format detail 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?

States a specific verb (Show/list) and resource (plugs), and helpfully defines what a plug is with concrete examples (reposting/resharing past a likes or reactions threshold). It also enumerates what is returned (config, activation state, recent runs). It does not name or differentiate against the obvious sibling configure_account_plug, so it falls short of a 5.

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

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

Usage is implied — an agent would use it to inspect an account's plug setup and history — but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as configure_account_plug for changing a plug. Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words elsewhere: it discloses ordering ('newest first') and the exact payload of each entry (posting frequency, pillars, gaps, average engagement, best posting time). It omits pagination or empty-result behavior, which keeps it short of a 5.

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

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

A single sentence with the action and scope front-loaded, followed by the enumeration of returned fields. Every clause carries information; nothing is redundant with the annotations or schema.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies enough return-value detail for an agent to know what it will get. Only edge-case behavior (no analyses yet, result limits) is left unaddressed.

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

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

The tool takes zero parameters, so the baseline is 4. The description uses the space productively by naming the returned fields rather than restating an empty input schema.

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

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

States a specific verb (List) and a precisely scoped resource (competitor accounts the user has already analysed), with the returned fields enumerated. It implicitly separates itself from list_personas (own personas) and analyze_competitor (which creates the analysis), but never names those siblings explicitly.

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

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

Usage is only implied: 'the user has analysed' hints that analysis must exist first and that analyze_competitor is the upstream action. There is no explicit when-to-use statement, no exclusion against list_personas, and no note about what happens when nothing has been analysed yet.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely new behavior: only active connected accounts are returned, and the result is a prerequisite input for schedule_post. It omits any note on result size/pagination, which keeps it short of a 5.

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

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

Two sentences, no filler. The scoping/return statement comes first and the prerequisite guidance second, both of which directly affect invocation.

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

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

With no output schema, the description carries the burden of describing results and does so (account ID, platform, display name). For a zero-parameter read-only list tool, an agent has everything needed to call it and consume the result.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies. The description correctly implies no filtering arguments are needed; nothing further is required or missing.

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

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

Specific verb+resource ('List the user's active connected social accounts') plus the returned fields (account ID, platform, display name). It is clearly separable from neighbors such as list_account_plugs, list_workspaces and list_publish_options.

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

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

Explicitly states when to call it ('Call this before scheduling') and why: schedule_post needs the connected_account_id. It also gives the eligibility rule that a post can only target a connected, active account, so the agent knows exactly when this tool is the right prerequisite step.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: a hard cap of 50 results, newest-first ordering, the status filter, and the fields returned, which tells the agent exactly what shape of result to expect.

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

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

A single sentence, front-loaded with the result cap and resource, then the filter, ordering and payload. No redundant restatement of the title or annotations.

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

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

With no input parameters and no output schema, the description bears the whole burden and mostly discharges it by specifying scope, cap, ordering and returned fields. The only gap is what happens beyond the 50-item ceiling (no pagination or cursor mention), which an agent calling the tool might want to know.

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

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

The tool takes zero parameters, so there is nothing to mis-specify and the schema cannot carry semantics. The description still adds value by enumerating the returned fields (platform, caption, hashtags, tone, source), which orients the agent despite the absence of any input.

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

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

States a specific verb (List) and a precise resource (draft post variants), and narrows the scope with the exact statuses (draft or pending_review) plus sort order. This distinguishes it cleanly from list_posts, review_drafts and generate_posts without opening any schema.

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

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

The description implies when this applies by naming the statuses it covers and noting the drafts come 'from generate_posts', which hints at the generate -> list -> review flow. However it never explicitly says when to use this instead of siblings like list_posts or review_drafts, so routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral facts: it never fabricates results (returns an empty list when no real signal exists) and it is entitlement-gated to the Empire plan, returning an upgrade message otherwise. Those failure modes and access constraints are exactly what annotations cannot express.

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

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

Three sentences, no filler, and the actual capability is front-loaded before the failure mode and the plan gate. Every sentence carries distinct information.

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

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

With no output schema, the description compensates by naming the returned fields (hashtag, growth, posting suggestion, empty-list guarantee), and with annotations covering safety it adds the plan gate. There is no parameter surface left unexplained, so an agent can call this confidently.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly adds no parameter text, and instead explains the implicit inputs (user's niches, connected platforms) that filter the output, which is useful framing rather than schema repetition.

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

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

The description gives a specific verb and resource ("List rising trends worth posting about now") plus the scoping constraints (user's niches, connected platforms) and the payload of each item (hashtag, growth, posting suggestion). That is enough to separate it from get_next_growth_opportunity and get_trend_hooks, though it never names a sibling outright.

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

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

Usage is implied by "worth posting about now" and the niche/platform restriction, but there is no explicit when-to-use vs when-not, and no mention of the obvious alternatives (get_trends, get_trend_hooks, get_next_growth_opportunity). The plan requirement is stated, which is a prerequisite rather than selection 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 the read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description adds genuinely useful behavior beyond them: plan gating and a graceful failure mode (upgrade message returned rather than an error), plus a description of the returned content.

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

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

Two tightly packed sentences with the purpose front-loaded and the plan constraint second. No filler, though the first sentence is a slightly dense list that could be parsed more quickly.

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

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

With no output schema, the description helpfully characterizes the return payload (per-platform guidance with source links) and the plan-gated edge case. It does not state the return format (list vs. object) or volume, but for a 0-param read tool it is nearly complete.

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

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

The tool takes zero parameters, so the schema carries no parameter semantics burden; the baseline for a 0-param tool is 4. No parameter detail is needed or missing.

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

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

States a specific verb+resource ('Get per-platform growth playbooks') and enumerates the payload (cadence, format, timing, anti-spam guidance, source links). It is clearly distinguishable from siblings like list_growth_opportunities or get_growth_overview by its documentation-derived content, though it does not name a sibling explicitly.

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

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

Provides a concrete prerequisite ('Requires the Empire plan; on other plans it returns an upgrade message'), which tells the agent when it will succeed. However, it gives no comparative guidance on when to prefer this over related tools such as get_growth_overview or list_growth_opportunities.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds useful behavior beyond them: deterministic ordering (newest first), fixed page size, and the fact that returned entries include a public URL — all of which matter for correct consumption.

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

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

One tightly constructed sentence front-loads the verb and resource, then appends ordering, page size, and the return-value hint in a compact em-dash clause. No filler, no restatement of the tool name.

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

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

For a single-optional-parameter read-only list tool with no output schema, the description supplies everything an agent needs: what is listed, ordering, page size, and what each entry yields (a public URL) plus where that URL is consumed. Nothing material is missing.

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

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

Schema coverage is 100% and the single `page` parameter is already documented in the schema. The description repeats the 24-per-page fact and adds the ordering semantic ('newest first'), which is not in the schema, but it offers no pagination-end or out-of-range guidance. 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?

States a specific verb (List) and resource (user's uploaded media library) plus scope details (newest first, 24/page). An agent can immediately distinguish it from the many other list_* siblings (list_posts, list_drafts, list_assets) because it is explicitly about uploaded media 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?

The description gives clear usage context by stating the returned URLs are 'usable directly in schedule_post's media_urls', which effectively routes the agent toward the downstream tool that consumes this output. It stops short of an explicit when-not or a named alternative for other media-fetching needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds two behavioral facts beyond that — results are returned newest-first and an unread count is included — which is genuine extra context, but nothing about pagination limits or how the unread count relates to the listed items.

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

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

A single sentence that front-loads the resource and packs the ordering and unread-count detail without filler. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing the return, and it does name the result set, ordering, and the unread count field. Pagination behavior is covered by the schema, so the only remaining gap is that the description doesn't indicate whether additional totals or a total-count are returned.

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%: page (1-indexed, default 1) and page_size (default 20, max 50) are fully documented in the schema. The description adds no parameter meaning beyond that, so the 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?

States a specific verb (List) and resource (the user's MisarPost notifications), and adds scope detail: what kinds of notifications (publish results, account problems), the ordering (newest first), and an included field (unread count). This clearly separates it from the sibling mutation tools mark_notification_read and mark_all_notifications_read.

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

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

Usage is implied by the verb and resource — an agent can infer this is the read path for notifications, and the presence of mark_notification_read/mark_all_notifications_read siblings makes the read-vs-mutate split natural. However, the description never explicitly says when to use this versus those siblings, nor does it state any prerequisites such as authentication or workspace scoping.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered externally. The description adds the default-status semantics, but says nothing about pagination, ordering, or scope (persona/workspace limits) beyond what the schema shows.

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

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

One sentence, zero waste, resource and default filter front-loaded. Nothing extraneous.

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-only list tool with full schema coverage and covering annotations, there is little an agent still needs. The only residual gap is result-shape/ordering information, which is minor here since no output schema exists and volume is small.

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

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

Schema coverage is 100% and the single enum parameter is fully documented in the schema, so baseline is 3. The description's gloss on 'pending' as 'waiting for review' adds mild interpretive value but no format or edge-case detail 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?

States a specific verb (List) and resource (AI-drafted replies to inbound comments and messages) with scope (by status). It implicitly separates itself from generate_persona_reply and review_persona_reply, though it never names those siblings to make the routing explicit.

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

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

The parenthetical clarifies the default filter (pending — the ones waiting for review), which hints at the review workflow, but it never says when to call this versus review_persona_reply or list_drafts, and offers no 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 establish readOnly, idempotent, non-destructive semantics, so the safety profile is covered. The description adds genuinely non-obvious behavior: the call also returns running extraction jobs and recent failures, not just personas. It does not mention pagination or result limits, but that is a minor gap given the annotation coverage.

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

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

A single front-loaded sentence with the primary action first and the secondary return content appended after the em dash. 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?

With no output schema and no parameters, the description usefully discloses the mixed shape of the return (personas + jobs + failures), which is exactly what the agent needs. It could have stated ordering or limits, but for a zero-arg read tool this is close to complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter information is required or missing.

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

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

States a specific verb (List) and resource (the user's PersonaForge personas), and defines what a persona is (writing styles learned from a real account). The 'user's' qualifier implicitly separates it from list_competitor_personas, though it never names that sibling explicitly.

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

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

Usage is only implied — an agent can infer this is the discovery/list entry point for personas, but there is no explicit when-to-use guidance and no mention of alternatives such as get_persona for a single persona or get_persona_job_status for job detail.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: sort order ('newest-scheduled first'), page size ('20 per page'), and the returned field set. It does not mention auth requirements, rate limits, or total-count behavior. No contradiction with annotations.

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

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

The purpose and sort/pagination facts are front-loaded, and the second sentence handles filtering efficiently. The mid-sentence field enumeration is a run-on but each field earns its place given there is no output schema.

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

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

With no output schema, the description correctly compensates by naming the returned fields, pagination size, and sort order. Only pagination termination/total-count behavior is left unstated, which is a minor gap for a default-filtered list 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%, so 3 is the baseline, but the description adds intent-level meaning to the status enum — tying 'pending/queued' to the content calendar and 'published' to what already went out — which the enum alone does not convey. tag_id and page get no extra color 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?

States a specific verb and resource ('List the user's scheduled and published posts') and enumerates what each row carries, so an agent can tell it apart from generate_posts or create_post_tag. It stops short of differentiating from close siblings like list_drafts or get_calendar, which also deal with post timing.

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 maps intent to filter values ('queued or pending for what is coming up — the content calendar — or published for what went out'), which is genuine usage guidance for the status parameter. However, it never says when to reach for this tool instead of list_drafts, get_calendar, or list_persona_replies, so the when-to-use dimension is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the shape of the returned data and how the returned ids feed other tools, which is real integration context an agent needs.

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

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

Two tight sentences with zero filler, front-loading what the tool returns before explaining how the result is consumed.

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

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

With no output schema and no parameters, the description carries the entire burden and does so: it enumerates the returned fields and explains the ids' role in other calls. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing to document and the description correctly does not invent parameter 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?

States a specific verb and resource ('List the user's post tags') and names the exact fields returned (id, name, colour), which cleanly separates it from siblings like list_post_templates, list_personas, and create_post_tag.

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

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

Explains the downstream purpose of the tool's output: tag ids filter list_posts and get_calendar and are applied via schedule_post or update_post. That gives clear context for why an agent would call it, but it names no exclusions or direct alternative to this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the discipline is low. The description still adds real behavioral context beyond them: the ordering guarantee ('most recently updated first') and the composition of a template. It stops short of describing return count/pagination.

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

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

A single front-loaded sentence leads with verb + resource + ordering, then uses the em-dash tail to define 'template' instead of adding a separate sentence. No redundant or filler text.

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 and annotations covering safety, the description is nearly sufficient, and its definition of template contents substitutes for a missing output schema. It could add a note on expected volume/pagination, so not quite perfect.

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

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

The tool takes zero parameters, so the schema provides nothing to disambiguate. Per the rubric, a 0-parameter tool earns a baseline of 4; there are no arguments whose meaning could be enriched.

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 (List) and resource (the user's saved post templates) and further defines what a template is (reusable composer states). It clearly distinguishes itself from the singular get_post_template sibling without needing to name it.

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

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

Usage is only implied: 'List the user's saved post templates' tells the agent what it does but not when to prefer it over get_post_template or create_post_template. No explicit when-to-use, exclusions, or conditions are given, which is the minimum-viable level.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world. The description adds non-obvious live behavior: it reads from the platform in real time, so an empty result can indicate connectivity failure rather than absence of destinations. That is genuine value beyond structured fields, though timeout/retry behavior and pagination are not addressed.

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, with the actionable follow-up (use ids in schedule_post) and the failure caveat at the end. The long platform enumeration is somewhat listy but it maps directly to the enum and earns its space.

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

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

With no output schema and a live-source tool, the description does the work of explaining what comes back (ids for platform_meta) and when an empty result is ambiguous. It omits the exact response shape and pagination, but for a lookup feeding schedule_post the essentials are present.

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 all three parameters are documented in-schema, so the baseline is 3. The description hints that the value kind must correspond to the account's platform (matching the schema note) but adds no syntax or format detail beyond what the schema already 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?

States a specific verb ('look up') and resource ('destinations a connected account can publish into'), then enumerates the exact platforms covered by the kind enum. An agent can distinguish this from siblings like list_connections or schedule_post without opening the schema.

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

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

Describes the downstream use case explicitly — 'Use the returned ids in schedule_post's platform_meta' — which tells the agent when this tool is needed. It does not state prerequisites (e.g., the account must exist and be connected) or when-not to use it, so it stops short of full routing 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=false, so the safety profile is covered. The description still adds real value by disclosing the sort order ('newest first') and the nested return structure (source plus variants plus engagement for scheduled ones), which the annotations 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?

One sentence, front-loaded with the verb and resource, and the colon-list packs the return shape densely without filler. It is slightly long but every clause carries information.

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

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

With no output schema, the description carries the burden of explaining return values and does so (source fields, variant list, status/URL/engagement for scheduled posts). Combined with full schema coverage for the lone parameter and complete safety annotations, nothing an agent needs is missing.

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

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

There is a single parameter and schema description coverage is 100%, with the default (20) and maximum (50) documented in the schema itself. The description adds nothing about the limit parameter, so the 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?

States a specific verb (List) and resource (past ContentRipple repurposes) and even enumerates the returned shape (source fields, variants, post status/URL/engagement). This clearly distinguishes it from siblings like list_posts and list_drafts, which serve different resources.

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 what is returned but never says when to reach for this tool versus alternatives such as repurpose_content, list_posts, or schedule_content_variant. There are no prerequisites, exclusions, or context cues to select it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the agent knows this is a safe, repeatable read. The description adds that the returned items are 'stock presenter avatars' whose ids are consumed downstream, but it does not describe return shape, pagination, or provider-specific behavior. Useful added context, but not rich 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?

Two tight sentences with zero filler; the purpose is front-loaded and the follow-on action comes second. Every clause earns its place.

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

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

For a simple, fully-annotated list tool with no output schema, the definition covers what it returns (presenter avatars) and how to use the result. Minor gaps remain around the concrete return structure, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100% for the single 'provider' parameter, whose enum-like note ('default heygen, currently the only one') is already in the schema. The description adds nothing about parameters, so the baseline 3 for schema-covered params 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?

States a specific verb and resource ('List the stock presenter avatars') scoped to 'AI video generation', and implicitly distinguishes itself from generate_video by being the catalog that feeds it. An agent can tell this is a read-only catalog lookup rather than a generation call without inspecting the schema.

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

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

Gives clear context for use ('available for AI video generation') and an explicit next step ('Pass an avatar's id to generate_video'), which routes the agent into the follow-on workflow. It stops short of naming the close alternative list_video_voices or stating when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully clarifies these are 'stock' voices rather than user-trained ones, but adds nothing about result size or pagination.

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

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

Two short sentences, no filler, with the core purpose front-loaded and the downstream usage hint following it.

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 zero-required-param list tool with no output schema, the description adequately implies that voice ids are returned and how to use them. Only the exact return shape is left implicit, which is minor here.

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

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

Schema description coverage is 100%, and the single optional provider parameter is fully documented in the schema (default heygen). The description adds no additional parameter meaning, 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?

States a specific verb (List) and resource (stock voices for AI video generation), which an agent can distinguish from the sibling list_video_avatars. It doesn't explicitly say why 'stock' voices differ from trained voice models, but the purpose is clear.

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

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

The second sentence, 'Pass a voice's id to generate_video,' routes the agent downstream but does not say when to call this tool versus alternatives like get_voice_model or train_voice_model. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it enumerates what is returned (URLs, subscribed events, active flag) and explicitly states that signing secrets are never returned, which is security-relevant behavior an agent should not assume.

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

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

Two tight sentences, front-loaded with the action and resource, followed by the return-shape detail. Every clause earns its place — the em-dash definition of 'webhook' is genuinely clarifying rather than filler.

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

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

With no output schema, the description must carry the return-value burden, and it largely does: URLs, events, active status, and the exclusion of signing secrets. Pagination or scoping behavior (e.g. per-workspace) is not addressed, but nothing else material is missing for a zero-argument list 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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; 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?

States a specific verb and resource ('List the user's outbound webhooks') and then defines what a webhook means in this product: URLs MisarPost posts signed payloads to. That domain framing separates it cleanly from create_webhook, update_webhook and delete_webhook without any ambiguity.

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

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

Usage is implied rather than stated — an agent can infer this is the read/inspect counterpart to create_webhook and update_webhook, but the description never says when to reach for it or what to do with the alternative tools. No exclusions or conditions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds genuine value beyond them by disclosing that when workspace scoping is on, posts, accounts and stats are restricted to the active workspace — a cross-tool behavioral effect an agent would not learn from the annotations or the empty schema.

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

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

Two short sentences with zero padding. The core action is front-loaded in sentence one, and the non-obvious scoping caveat follows immediately.

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

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

For a no-parameter, fully annotated read tool with no output schema, the description covers purpose and the main behavioral nuance. It stops short of 5 only because it says nothing about what a returned workspace contains or how the list is ordered, which is a minor gap here.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 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?

States a specific verb and resource: listing the workspaces the user belongs to, plus the scoping semantics of the active workspace. No sibling tool competes for this resource, so differentiation is implicit rather than explicit, which keeps it just short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The second sentence explains a consequence of workspace scoping, which is context rather than routing guidance; usage is only implied by the tool's obvious role as the workspace enumerator.

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=false, destructiveHint=false, and idempotentHint=true. The description adds the one genuinely non-obvious trait beyond that: the change is irreversible ('no way to mark them unread again'), which materially affects an agent's caution. It does not cover auth requirements or scope boundaries (e.g. all workspaces), keeping it short of a 5.

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

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

Two short sentences, front-loaded with the action and followed by the irreversible consequence. No filler and nothing an agent must wade through.

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 mutation with full annotation coverage and no output schema, the description supplies the essential facts: what changes and that it cannot be undone. Only explicit sibling routing is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no targeting/filter arguments are 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?

States a specific verb ('Mark'), a precisely scoped resource ('every unread notification'), and the resulting state ('as read'). The 'every' scope cleanly distinguishes it from the sibling mark_notification_read, which handles a single notification.

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

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

Usage is implied by the bulk scope: an agent can infer this is the batch variant versus the singular sibling. However, the description never names mark_notification_read or states a condition for choosing between them, so routing is left to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and non-read-only, so the safety profile is covered. The description still adds a real behavioral fact beyond the structured data: the notification "drops out of the unread count," telling the agent the observable side effect on state.

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

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

Two short sentences: the action and scope come first, the effect and a usage example follow. Every clause earns its place with no filler.

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

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

For a one-parameter mutation with full schema coverage and safety annotations, the description covers purpose, trigger, and side effect adequately. It omits only edge behavior such as what happens when the notification is already read or an invalid UUID is supplied.

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

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

Schema description coverage is 100% and the single parameter is already documented as a 'Notification UUID — from list_notifications.' The description adds no format, provenance, or error semantics 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?

States a specific verb (mark read) and resource (notification) plus the singular scope, which implicitly separates it from the sibling mark_all_notifications_read. It never names that sibling explicitly, so the differentiation is inferred rather than stated.

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?

"e.g. after relaying it to the user" gives a concrete trigger condition for when to call this. There are no explicit exclusions or a named alternative (mark_all_notifications_read) for bulk cases, so timing guidance is clear but alternatives are left to inference.

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

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

Goes well beyond the annotations by disclosing quota/consumption behavior: it counts against the monthly repurpose limit and burns one AI text action, which is exactly the kind of side effect an agent needs before invoking. It does not describe auth requirements or the shape of the extracted result, so it stops short of a 5.

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

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

Two sentences, front-loaded with the action and output, then the cost/alternative guidance. Every clause carries information; nothing is padding.

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

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

No output schema exists, yet the description adequately conveys what comes back (core message, key points, structure) and warns about quota cost. The only remaining gap is any detail about how the parsed result is delivered or limited in size.

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

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

Schema description coverage is 100%, so the enum values and conditional requirements are already documented in structured fields. The description only echoes the input forms and the 50-20,000 character bound already present as min/max in the schema, adding no interpretive value.

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

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

Specific verb (extract) plus the exact resources produced (core message, key points, structure) and the accepted input forms (URL, pasted text, Markdown). It also explicitly names the sibling it is not (repurpose_content) and the difference (no variants), so an agent can distinguish it immediately.

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 states both when to use it ('a preview of what repurpose_content would work from') and when not to ('prefer repurpose_content when the user wants variants anyway'), naming the alternative and the selecting condition. Little is left to inference.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the fan-out behavior — one draft per snapshot per connected platform — and confirms the output lands in the draft queue rather than being published. It stops short of warning about duplicate creation on repeat calls, which the non-idempotent hint implies.

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

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

One front-loaded sentence naming the transformation, the fan-out, and the destination, plus a short safety clause. No filler and every clause carries information.

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

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

With no output schema, the description helpfully names list_drafts so the agent knows how to retrieve the created drafts. It does not say what the call itself returns (e.g., created draft identifiers), which is the one remaining gap for a creation tool.

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

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

Schema description coverage is 100% and the single parameter is already documented as '1–3 trend snapshot UUIDs — from get_trends.' The description restates the same bound and provenance without adding format or syntax detail, so the 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?

States a specific verb and resource ('Turn 1–3 trend snapshots into draft posts') with the source (get_trends) and destination (draft queue / list_drafts) named. It clearly distinguishes itself from schedule_trend_posts and generate_trend_platform_content by declaring that nothing is scheduled or published.

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 when to use it (when you hold 1–3 snapshots from get_trends) and implicitly excludes the scheduling sibling by stating nothing is scheduled or published. It does not name an alternative explicitly, so it falls just 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 it is a non-readonly, open-world, non-idempotent write. The description adds genuinely useful context beyond that: the plan gating that produces an upgrade message instead of a refresh, and the fact that it stores new snapshots. It stops short of noting cost/latency of fetching every source or whether snapshots append or replace, so not a full 5.

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

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

Three short sentences, front-loaded with the core action, then the gating prerequisite, then the follow-up read. Every sentence carries distinct operational information with no padding.

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