VoiceMoat

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return content (impressions, likes, replies, retweets, post count, top post), which matters because there is no output 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 sentences, zero waste: the first front-loads what is returned and the second front-loads the trigger conditions. 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 describes the returned metrics and top post, and defaults are covered by the schema. It could go further by noting that the window defaults to last_7_days and platform to the active platform, but nothing essential 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% with both params enums and defaults documented in the schema. The description only echoes 'for a time window' and adds no syntax or format detail 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 (Get) and resource (engagement totals and top post) and enumerates the exact metrics returned, which implicitly separates it from single-post siblings like get_post and list_posts. An agent can tell what this returns 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 says when to use it with concrete user phrasings ('how their posts performed', 'how yesterday went', 'how they're trending'). It lacks a when-not clause or named alternative, but the intended trigger 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value by disclosing the returned fields, which matters because no output schema exists. It stops short of stating auth requirements or error behavior, but for a read-only self-lookup that is minor.

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, zero waste, and the return contents are front-loaded before the usage cue. Nothing could be trimmed without losing information.

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

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

With no output schema, the description carries the burden of describing the response, and it does so by naming the three returned fields. Complete enough for a trivial no-arg read; only the absence of any error/edge-case note (e.g., unauthenticated caller) keeps it off a 5.

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 correctly implies a parameterless call by framing it as 'the signed-in account' rather than requiring an identifier.

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 signed-in account) and enumerates exactly what comes back: email, plan, and whether the plan permits assistant connection. An agent can distinguish it from siblings like list_profiles or get_voice_profile, which concern other people's profiles rather than the caller's own account.

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 names the trigger: 'Use when the user asks which VoiceMoat account or plan they are connected with.' It doesn't name alternatives or exclusions, but the selection condition 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully discloses the payload (full text plus engagement numbers) but says nothing about behavior on an invalid or unknown id, and there is no pagination/error context.

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

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

Two short sentences, with the core capability front-loaded and the usage trigger second. Every clause carries information and nothing is padded.

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-resource read with no output schema, the description tells the agent what comes back (full text and engagement numbers), which compensates for the absent return schema. Minor gaps around invalid-id behavior remain, but nothing essential to calling 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?

Schema description coverage is 100%; the schema already documents that post_id accepts a tweet id, LinkedIn URN, or VoiceMoat id. The description's "by id" adds no 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 (fetch), resource (one post), and scope (full text + engagement numbers, by id), which cleanly separates it from the plural sibling list_posts and the aggregate get_analytics.

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?

"Use when the user references a specific post and you want exact numbers" is an explicit positive trigger condition. It stops short of naming an alternative (e.g. list_posts for browsing) or stating when not to use it, so it is clear context without 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 only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). With no output schema, the description usefully discloses the shape of the result: 'Each idea is a short seed, not a full draft.' It still says nothing about latency, cost, or how ideas differ from one another.

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 what it produces, followed by when to use it and what the output looks like. 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?

All three parameters are documented and the non-draft nature of the result is explained, which is the main gap given no output schema. Slightly incomplete in that it doesn't hint at how many ideas the default yields or how platform affects output, but nothing essential 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 topic, count, and platform are each documented in the schema, including the count default of 5 and the platform omission rule. The description adds only 'N distinct', which is a restatement of count rather than new semantics. 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 ('Generate') and resource ('post ideas') with the key qualifier 'N distinct' and 'on a topic'. It also implicitly separates itself from siblings like suggest_hooks and improve_post by clarifying the output is a seed rather than a draft.

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

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

'Use when the user asks for ideas, angles, or different takes on the same subject' gives a clear triggering context. It stops short of naming alternatives (e.g. suggest_hooks for openers, search_inspiration for existing content) or stating when not to use 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=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-annotated behavior: it returns empty results if the user has never run Voice Lab, and it names Voice Lab in VoiceMoat as the prerequisite surface. Return format/pagination is unspecified, but the empty-case disclosure is valuable.

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-loads what the tool returns, then usage triggers, then the empty/prerequisite caveat. Mostly tight, though the trailing 'Voice Lab in VoiceMoat is where they run it' is slightly redundant with the opening mention.

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

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

No output schema exists, so the description appropriately describes the returned content and the empty-result case. It is complete enough to call correctly for a single-optional-param read tool, missing only minor depth on result shape.

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 platform enum is fully documented in the schema, so baseline 3 applies. The phrase 'for one platform' does mirror the schema's scoping but adds no new 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+resource (latest Voice Lab analysis) and enumerates the concrete contents: dominant voice patterns, hook styles, sentence rhythm, vocabulary, plus a drift reading. An agent can tell this apart from get_voice_profile or score_voice_match because the source (Voice Lab) and payload are named 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?

Gives two explicit trigger conditions: 'when the user asks what their voice patterns are' and 'whether they are drifting.' It does not name alternative siblings (e.g. get_voice_profile) or state when not to use this tool, so it falls short of full when/when-not/alternatives 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 readOnly/destructive/openWorld hints, and the description's 'Read-only' is consistent with them. It goes further by disclosing the substantive content of the profile (including negatively-framed data like phrases the user never uses), which is meaningful context given there is no output schema and no pagination or filtering caveats to 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 tight sentences: the first states what is returned, the second states when to use it. Nothing is redundant or buried, and the resource description is front-loaded.

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

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

For a zero-required-parameter read tool with no output schema, the description supplies the key missing piece — the shape of the returned profile — and confirms safety. The only gap is sibling disambiguation against get_voice_insights.

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 platform enum plus its default are fully documented in the schema. The description only gestures at the scoping with 'for one platform', adding no format or selection detail beyond what the schema already provides, which lands at the baseline.

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

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

The description names a specific resource (the user's trained voice profile) and enumerates its contents (persona, tone markers, traits, avoided phrases), so the agent knows exactly what comes back. It fails to explicitly differentiate from the closest sibling, get_voice_insights, leaving the boundary to inference.

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 trigger condition: use when the user asks what their voice is like or what to keep and avoid. However, it names no alternative and no when-not condition, so an agent facing a general 'tell me about my writing' request has no routing guidance against get_voice_insights or list_profiles.

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

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

Despite annotations covering the safety profile (readOnlyHint=false, destructiveHint=false), the description adds substantial context: credit costs per mode, that nothing is saved or posted, and what each mode produces. It clearly discloses the side-effect boundary ('the result comes back to the user to accept or ignore').

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-loads purpose, then modes, then usage and cost, so it is well-ordered. It is on the dense side, and the opening clause about the 'Improve panel in Content Studio' is marketing framing that does little for agent decision-making, keeping 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 compensates by describing return values ('the improved post with what changed and why', '2 to 3 alternative rewrites'). For a non-destructive, credit-metered tool it covers mutation boundary, cost, and output shape completely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above the baseline by unpacking the 'full' mode as an ordered pipeline (grammar, opening line, line breaks, platform formatting), which adds meaning beyond the schema's terser mode definition.

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 ('Improve a draft') and elaborates with named modes ('full' vs 'quick') plus the internal engine it uses. An agent immediately understands the operation. It does not explicitly name or distinguish itself from adjacent siblings like suggest_hooks or score_voice_match, so it falls 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?

Gives clear triggering conditions ('Use when the user asks to improve, tighten or fix a specific draft') and a constraint ('once per text', 'for text the user asked to improve'). It also surfaces the credit cost (quick 3, full 5) to inform selection. It stops short of naming alternative tools for the adjacent tasks.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the bar is lower, and the description still adds real context: platform scoping, that an empty list is returned when no creators exist, and where in the product the user can add some. It does not describe ordering or truncation behavior beyond what the schema already 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?

Three tight, front-loaded sentences: what it returns, when to use it, and the empty-state/platform caveats. Every sentence earns its place, though the framing sentence is slightly dense and the empty-state note could be trimmed.

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

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

For a simple, optional-param, read-only list tool with no output schema, the description covers the essentials an agent needs: what is returned, platform scoping, the empty-result case, and the user-intent triggers for calling it. Nothing needed to select or 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents limit, its range, default and 'strongest first' ordering. The description adds nothing about the parameter, making baseline 3 the correct score.

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

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

The description states a specific verb+resource ('The creators the user has analyzed or learned from on the current platform') and even enumerates the returned data (topics, signature opening-line patterns), so the agent knows exactly what set it gets. It does not explicitly contrast itself with lookalike siblings such as list_profiles or get_post_ideas, which keeps it from 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?

Clear when-to-use triggers are given: 'Use when the user asks for ideas or a post like the creators they follow or study, or asks who they have been learning from.' It also scopes to Twitter/LinkedIn and the active platform. It names no alternatives or when-not-to-use conditions (e.g., search_inspiration or get_post_ideas), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful behavioral context that results are ranked by likes and limited to a window, but says nothing about result size limits or caps beyond what the schema states, so it only modestly exceeds the annotation baseline.

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 capability and its sort/scope constraint are front-loaded in sentence one, and the usage trigger 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 two-optional-parameter, read-only list tool with no output schema, the description covers purpose, ranking, scope, and trigger conditions adequately. It could say a bit more about what each returned post contains, but nothing critical to 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 description coverage is 100% and both parameters (limit, window) carry their own descriptions and enum values, so the schema does the heavy lifting. The description reinforces the time-window concept but adds no format or default details beyond the schema. 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 with an added ranking and scope qualifier: 'List the user's best-performing posts (sorted by likes) in a time window.' The ranking and ownership scoping implicitly separate it from siblings like get_analytics (metrics) and get_post (single post), but no sibling is named 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?

Gives concrete trigger conditions: 'what worked,' 'what went viral,' 'examples of their best content' — an agent can match user intent directly. It stops short of explaining when NOT to use it or which sibling to prefer for adjacent needs (e.g., get_analytics for raw metrics).

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description need not restate it. It adds real value by disclosing the return contents and the cross-tool linkage of account_id, though it says nothing about behavior when no profiles are connected or about 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?

Three sentences, front-loaded with the resource and return fields, then the trigger, then the downstream linkage. Every sentence earns its place, though the account_id sentence is slightly redundant with the field enumeration in the first sentence.

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 tool with no output schema, the description carries the whole load and does so: it says what is returned, which fields matter, when to call it, and how the ids are consumed downstream. 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?

The tool takes no parameters, so the baseline is 4. The description correctly adds no parameter detail, and its mention of account_id describes an output field rather than an input, which is the right thing to clarify for a zero-argument tool.

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 resource (Twitter and LinkedIn profiles connected to the VoiceMoat account) and enumerates the returned fields (account id, handle, display name, default platform). It is clearly distinguishable from every sibling, none of which list connected accounts.

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 trigger: 'Use when the user asks which profiles are connected or which one they are on.' It also routes downstream by noting account ids are what publish_post and schedule_post consume. It stops short of naming a when-not-to-use or a competing alternative, so it is clear context rather than 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 flag a destructive, open-world write, and the description adds the crucial behavioral detail beyond them: the first call posts nothing and returns a preview plus token, and posting happens only after explicit confirmation. It also discloses platform-specific behavior (dash-separated blocks become a chained X thread), which an agent cannot infer from annotations or 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?

Three sentences, front-loaded with the core action, then the required call sequence, then a platform nuance. Every sentence carries actionable information with no restatement of 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?

For a destructive, open-world publish tool with no output schema, the description covers the safety-critical elements: what the first call returns (preview + token) instead of posting, the confirmation gate, and the multi-account/thread behavior. Nothing needed 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 coverage is 100%, so parameter documentation is already strong, but the description adds the workflow semantics that tie confirmation_token to the two-phase preview/confirm cycle rather than just describing the field in isolation. The dash-thread formatting note adds content-level meaning that the schema does not capture.

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 ('Publish a post') plus the target surfaces ('the user's LinkedIn or X account immediately'), which cleanly separates it from siblings like schedule_post, improve_post, and get_post_ideas. An agent can identify the tool's job 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 an explicit two-call protocol: first call without confirmation_token to obtain a preview and token, show the user, then re-call with identical arguments only on agreement. It also names the alternative paths (preview vs. actual publish) and the condition that selects each, leaving nothing 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 flag destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: the preview-first flow that posts nothing on the first call, the token handshake, and the concrete time constraint (UTC ISO-8601, at least ten minutes ahead). This is exactly the kind of behavioral detail an agent needs to avoid an accidental publish.

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

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

Three sentences with no waste; the scope constraint is front-loaded and the two-step confirmation flow follows immediately. Every sentence carries an actionable instruction.

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

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

With no output schema, the description covers the important return behavior by stating the first call returns a preview and a token. Combined with annotations covering the safety profile, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by explaining the semantics of confirmation_token as a call-pattern switch (absent = preview only, present = commit) and reiterating the scheduled_for constraint, which is more than restating the schema field text.

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

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

States a specific verb and resource ('Add a post to the user's scheduled queue') plus the outcome ('publish unattended at a time they choose'), which clearly distinguishes it from an immediate-publish tool. It does not explicitly name the closest sibling (publish_post), so the differentiation is implied 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?

Gives an explicit two-phase invocation protocol: call once without confirmation_token, then again with the token only after user consent. That is clear when-to-use guidance, but it never names the alternative tool (e.g., publish_post for immediate posting) or states when not to schedule.

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

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

Annotations are minimal (readOnlyHint=false, openWorldHint=false, destructiveHint=false), and the description adds substantial context beyond them: the two-result structure with no blending, a 1-credit cost for Stance, that Stance only runs when the claim bank has items and the text asserts something, that Style is free, and that text is 'checked once.' This also explains the non-read-only annotation (credit consumption). 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?

The core distinction (two separate results, no blended score) is front-loaded, and each subsequent clause earns its place by defining Style, Stance, cost, and gating conditions. It is dense and somewhat run-on, but there is little waste.

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

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

There is no output schema, so the description carries the burden of describing returns — and it does: Style as 'N of M checks' with named checks and an example line, Stance as 'On voice / Check one line / Off voice' with flagged lines and matched claims. For a single-parameter tool this is complete enough to call and interpret 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?

There is a single parameter with 100% schema description coverage, so the schema already documents the 'content' field and its 8000-character scoring limit. The description restates 'the exact text to score' but adds no syntax, formatting, or truncation behavior beyond what the schema states. Baseline 3 applies 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 specific verb+resource — checking a piece of text against the user's voice — and immediately disambiguates the output into two distinct results (Style vs Stance). It also explicitly states 'There is no blended voice score,' which separates it from any generic improve/score sibling like improve_post. An agent can identify the tool's function 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?

It gives clear triggering conditions: 'Use when the user asks whether a draft sounds like them, is on voice, or is something they would write, including a draft written for them in this conversation.' It also scopes Stance to claim-bank items and text that states something checkable. It does not explicitly name a sibling alternative (e.g., improve_post) to route away from, so it stops short of full when/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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them: cost ('free to run'), platform bound ('LinkedIn only'), what the results represent, and the crucial empty-result semantics ('nothing matched, not that the user has no posts'). It stops short of describing pagination or result shape.

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, each earning its place: what it is, when to use it, and what the results mean. The scope statement is front-loaded before the invocation triggers.

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: it says the results are other creators' public posts and explains the empty-result case. Combined with full schema coverage and clear annotations, 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?

Schema description coverage is 100%, so all four parameters (limit, query, creator, media_type) are already documented in the schema, including the semantic-matching hint on query. The description adds no parameter-level detail beyond that, making 3 the correct 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?

Names a specific verb (Search) and a precisely scoped resource: the shared LinkedIn inspiration corpus of public posts from tracked creators, equated to the Inspiration > Explore tab. It also separates itself from siblings like list_posts and get_post_ideas by stating the results are other people's posts, never the user's own draft.

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

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

Gives four concrete triggering scenarios (what's working in a niche, examples of posts on a subject, how others open a post, what a named creator has been posting). It also constrains scope with 'LinkedIn only, and free to run' and implicitly routes own-draft needs elsewhere via the reference-material note.

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=false and openWorldHint=false, so the safety profile is largely covered. The description usefully adds that output is exactly three lines drawn from distinct angles, but it says nothing about voice/profile usage, determinism, or rate behavior for a generation tool.

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, and the core output definition is front-loaded ahead of the usage trigger. 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 returns and does so (three hooks, five possible angles). It is nearly complete, though it omits whether the user's voice profile influences generation, which is implied by sibling tools like get_voice_profile.

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 'topic' (1-240 chars) and the 'platform' enum with its omit-to-inherit semantics are already fully documented. The description adds no parameter-level 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?

Specific verb ('Generate') plus resource ('opening lines/hooks') with an exact output count (3) and enumerated angles (contrarian, story, listicle, reframe, observation). This distinguishes it from the nearby get_post_ideas and improve_post siblings, which operate on full posts rather than first lines.

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

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

Explicitly states when to use it: 'when the user asks for a hook, a first line, or doesn't know how to start.' That is clear routing context, but it names no alternatives or when-not conditions (e.g., versus get_post_ideas), 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.