DemandBird

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

Annotations already mark this as a non-read-only, non-destructive, closed-world mutation. The description adds useful behavioral detail beyond annotations: existing times are left unchanged and already-queued posts keep their times, which clarifies side effects.

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

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

The description is four short sentences and front-loads the core action. Each sentence adds useful information about format, timezone, and mutation behavior without repetition.

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

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

Given the complete input schema, annotations, and absence of an output schema, the description supplies enough context to call the tool correctly: purpose, time format, timezone source, duplicate handling, and effect on queued posts. No critical gap remains.

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 schema already documents the parameters well. The description still adds meaningful interpretation by specifying that times are in the workspace's posting time zone, which is not stated in the schema.

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

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

The description states a specific verb and resource: adding posting times to one channel's weekly queue schedule. It clearly distinguishes this mutation from related siblings such as remove_queue_times and list_queue_schedule by naming the exact operation and scope.

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

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

The context is clear: use this to add recurring posting times to a channel's weekly queue. It also points to list_queue_schedule for the workspace posting time zone and notes duplicate-time behavior, though it does not explicitly name when to prefer queue_post or remove_queue_times.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing the human-in-the-loop contract: show the link and wait, the verdict belongs to the reviewer, invented confirmation arguments are silently ignored. This is exactly the behavioural nuance 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?

Front-loads the return-a-link behaviour and keeps the sibling pointer last. Some redundancy ('does NOT approve', 'do not try to confirm on their behalf') but it is deliberate emphasis for a failure mode agents commonly get wrong, so it mostly 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 does state the return value (a link the user opens), which is the critical piece. It leaves the exact response shape and the role of `note` unstated, a minor gap for a 2-parameter tool.

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

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

Schema description coverage is 100%, so post_id and note are already documented, which sets the baseline at 3. The description adds nothing about either parameter's meaning or format, and notably does not reconcile the `note` field ('recorded with the approval') with the claim that the tool does not approve.

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 and unusual verb+resource: it returns a URL for a human to approve a post, and explicitly says it does not itself approve. That distinction separates it cleanly from publish_post and queue_post 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?

Gives explicit when-to-use context (a post awaiting the user's review), explicit when-not behaviour (do not confirm on their behalf, invented arguments are ignored), and names the discovery sibling `list_posts_awaiting_my_review`.

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

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

Annotations only declare write + open-world + non-destructive; the description adds genuinely new facts: no AI call, post copy untouched, approval state not reset, background URL fetch with link retained on failure, and a hard 20-reference cap. That is exactly the context 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?

Five short sentences, front-loaded with purpose, then the anti-pattern warning, then the exclusivity rule, then behavioral guarantees. Every sentence carries distinct decision-relevant 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?

For a 4-param mutation with no output schema, the description covers the mutation's side effects, limits, exclusivity rule, and safety profile. Nothing an agent needs in order 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 already 100%, yet the description still adds a constraint absent from the schema: 'exactly one of text or url' (the schema has no oneOf and only requires post_id). It also explains the background-fetch behavior tied to `url`, which is the parameter's real semantics.

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

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

Specific verb ('attach') plus resource ('source material to a post') with explicit scope: stored WITH the post, readable by author/reviewers, not in post copy. It cleanly distinguishes itself from save_draft/update_draft by warning against putting source text in `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?

Explicit when-to-use ('anything the post was written from') and when-not-to-use ('NEVER paste a transcript or source text into content'), and it names the sibling tools that take content instead. No inference required.

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 is a non-destructive mutation, but the description adds meaningful behavioral detail: the post returns to drafts and is not deleted. It does not cover edge cases such as what happens if the post is not currently scheduled, but it is substantially transparent for the operation.

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

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

Two short sentences, front-loaded with the action and then the outcome. There is no wasted language, and the key non-destructive guarantee appears 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 simple one-parameter mutation with full schema coverage and explicit annotations, the description covers what an agent needs: what the tool does, what state change occurs, and that nothing is deleted. No output schema exists, so return-value detail is not required.

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 fully documents the single required parameter ('id' with description 'Post id'). The description adds no parameter-specific meaning, so the baseline of 3 is appropriate given 100% schema coverage.

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

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

The description states a specific verb and resource ('Take a scheduled post back off the queue') and immediately clarifies the resulting state ('returns to drafts'). It also distinguishes itself from a destructive sibling like delete_post by explicitly saying 'nothing is deleted'.

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

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

The description provides clear context: it is for scheduled posts and moves them back to drafts. It does not name alternatives such as delete_post or pause_queue explicitly, but the 'nothing is deleted' contrast gives useful usage 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?

The annotations already establish that this is a non-destructive mutation. The description adds useful behavioral context beyond the annotations: it 'decides nothing and blocks nothing' and stores the text verbatim, which helps an agent understand the effect of the 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?

The description is front-loaded and efficient. There is mild redundancy between 'without approving or sending it back' and 'Decides nothing and blocks nothing,' but the sentences remain useful and compact.

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 two-parameter mutation with no output schema and clear annotations, the description covers purpose, usage context, and behavioral effect sufficiently. An agent has what it needs to call the tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description reinforces that the comment text is stored verbatim, but that meaning is close to the schema's own wording and adds little about post_id.

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

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

The description gives a specific verb and resource: 'Leave a comment on a post.' It also distinguishes the action from approval or rejection by saying 'without approving or sending it back,' which cleanly separates it from siblings like approve_post and send_back_post.

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

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

It states clear use cases ('feedback, a question, or a note in passing') and an implicit when-not-to-use condition by contrasting with approval/send-back behavior. It does not name the alternative tools explicitly, but the selection guidance is 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?

Goes well beyond destructiveHint=true: it discloses all-or-none semantics, the exact failure condition (missing id or another user's idea without admin rights), the fact that the reply names the offending ids, and cascading deletion of sources, tags and images with no undo. This is precisely the pre-call risk information an agent needs before a destructive bulk operation.

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

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

Four tight sentences front-loaded with scope, then atomicity, then irreversibility. The opening clause "by the ids `list_ideas` and `save_idea` give" is slightly awkward phrasing but carries real information, so nothing 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?

For a single-parameter destructive tool with no output schema, the description covers scope, input origin, atomicity, permission rules, error reporting and cascade side effects. Nothing an agent needs to decide or 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%, including the max-100 limit, so the baseline is 3; the description adds provenance (ids come from list_ideas/save_idea) and the constraint that ids must belong to this workspace or the caller's own ideas, which the schema does not express. Meaningful value beyond the schema, though not exhaustive.

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 (ideas in the Ideas tab of the active workspace) and distinguishes itself from siblings by naming list_ideas and save_idea as the id sources. An agent knows exactly what this does and what it operates on 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?

"Use it to undo a wrong save_idea" gives a concrete triggering scenario, and the mention of list_ideas tells the agent how to obtain the required input. It does not contrast with delete_post or other removal-ish siblings, so there is no explicit when-not guidance, but the intent 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the agent knows this is an in-world destructive write. The description adds only the draft-only scope; it does not mention irreversibility, whether a deleted draft can be recovered, what happens if the ID refers to a published or scheduled post, or what error behavior to expect. With annotations carrying the safety profile, this partial addition merits a 3.

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 short sentence with zero waste, front-loaded with the verb and resource. It is efficient, though the extreme brevity means there is no room for the scoping or recovery caveats a destructive tool would benefit from.

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 tool with full schema coverage and existing annotations, the description covers the essentials. Still missing for a destructive operation are persistence/reversibility behavior and what happens when the target is not a draft, which an agent would need before calling it 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?

There is a single required parameter with 100% schema description coverage ('Post ID to delete'), so the schema already fully documents it. The description adds nothing about ID format, whether IDs come from list_drafts or get_post, or how to obtain a valid ID, 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') plus resource ('a draft post') and the lookup key ('by ID'), so an agent can distinguish it from delete_idea or cancel_post. It does not explicitly name which sibling to use instead for non-draft posts, keeping it below 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?

The word 'draft' implicitly scopes usage to draft posts only, which is useful guidance. However, there is no explicit statement of when to use delete_post versus cancel_post, remove from queue, or delete_idea, and no prerequisites or exclusions 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 flag readOnlyHint=false and destructiveHint=false, so the description adds meaningful context: generation runs through the workspace voice engine (positioning/audience/pillars) and persists as a draft, not a published post. It also hints at a 'Need more to draft this' non-success outcome via draft_anyway, though it doesn't cover latency/cost of generation.

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 with the gating rule front-loaded and the alternative routing at the end. Minor redundancy between 'PREFER this over...' and the voice-engine justification, 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?

For a generative mutation tool with no output schema, it conveys the destination (a saved draft), the voice/brand dependency, and the insufficient-context fallback. The return shape is only partially implied, keeping it short of full completeness.

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

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

Schema description coverage is 100%, so parameters are already fully documented; the description adds no parameter-level detail beyond what the schema states (prompt is not elaborated on). 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 — AI-generates post content and saves it as a draft — and explicitly contrasts with the sibling save_draft plus the pivot of writing it yourself.

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 ('ONLY when the user explicitly asks AI to write/generate/compose'), an explicit exclusion ('Do NOT use when the user provides their own content'), and names the alternative path (writing it yourself then save_draft).

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, and the description reinforces this with 'Saves nothing' — a genuinely useful disclosure that the generated alternatives are not persisted anywhere. It stops short of saying whether variants draw on brand voice/account context or how they are presented, but the critical non-persistence behavior is 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 with zero waste: capability first, non-persistence second, then the routing example and the exclusion. Front-loaded and easy to scan.

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

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

For a read-only, single-parameter tool with no output schema, the definition covers what it produces (three alternatives), that nothing is saved, and when to prefer a sibling. Only minor gap is whether the returned variants are plain text only or carry any identifiers the agent could act on.

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 at 100% coverage ('Post id'). The description adds marginal value by framing it as an 'existing draft' and showing a concrete id in the usage example, but adds no format details beyond the schema 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 and resource ('produce three alternative versions of an existing draft') with a clear cardinality (three) and a scope limit ('to read'). An agent can immediately tell this apart from revise_draft and other draft-mutating 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?

Gives an explicit when-to-use example ('give me a few other versions of 123') and an explicit when-not-to-use case ('shorter', 'less salesy'), naming the correct alternative revise_draft and explaining how its behavior differs. Nothing 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?

Adds substantial context beyond the annotations: latency (10-30s), cost (one monthly image credit) and that balance is returned, channel-specific return handling (s3_key over MCP, attachment over SMS/WhatsApp), and persistence to the media library. This is exactly the behavioral detail annotations don't convey.

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

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

Front-loads the purpose and the key style instruction, then packs cost, return, and alternative into dense but earning sentences. Slightly long, but nearly every clause carries actionable 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?

Despite no output schema, the description fully explains what is returned on each channel and how to use it downstream (images field of draft tools), plus cost, timing, and persistence. Nothing needed 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%, so the baseline is 3. The description adds genuine semantic guidance beyond the schema for the prompt ('Describe the picture, not the post') and the do-not-restate-style rule, which shapes how the required parameter should be filled.

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 an original image with AI') and its purpose ('to accompany a post'), and explicitly differentiates from the sibling upload_image. An agent can distinguish it instantly.

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 ('accompany a post'), a key instruction ('do NOT restate colours or visual style'), and names the alternative with its selecting condition ('Use upload_image instead when the user already has a picture').

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 'Read-only' is largely redundant, but the description adds genuine behavioral context beyond them: that every metric is reported with a period-over-period change, and that LinkedIn additionally returns a six-way reaction breakdown. It does not mention empty-state behavior when no accounts are connected, nor pagination/limits, which keeps 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?

Front-loads the capability then immediately states the without-platform vs with-platform branch, which is the right ordering. The multiple quoted example utterances are useful for intent matching but make the middle slightly denser than necessary; still, no sentence is pure 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 does the work of naming the returned metrics and the delta semantics, and it explains the two calling modes. It is slightly incomplete on what a caller should expect when no platform is connected or when a custom range conflicts with period, though the schema covers the override rule.

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 schema text already explains that omitting platform yields a cross-platform roll-up, so the description mostly restates it. It adds a small amount by tying the platform choice to user intent phrasing and noting LinkedIn's special reaction output, but period/start_date/end_date are not discussed in the description at all. 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-and-resource pair (answer performance questions about an account) and enumerates the exact metrics returned (followers, engagements, reach/impressions/views, engagement rate) with a period-over-period delta. This clearly separates it from siblings like get_post_analytics, get_follower_history, and get_audience_demographics, which cover narrower 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?

Gives explicit branching rules: call WITHOUT platform for a cross-network roll-up, pass platform to focus on one network, and supplies representative user utterances for each branch ("how am I doing?", "how's twitter doing?"). The schema also notes start_date overrides period for custom windows, so the routing story is complete.

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

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

Annotations already declare readOnlyHint and non-destructive, so the trailing 'Read-only' adds nothing. The valuable disclosure is the per-platform coverage map (Instagram/Threads country/age/gender/city, LinkedIn page seniority/function/industry/size/location) and the explicit statement of what is not available, which the 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: questions first to aid matching, then exact coverage, then the negative case. Every sentence adds information and nothing is repeated from structured fields.

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 does enough by enumerating the dimension names returned per platform, so an agent can anticipate the response shape. It leaves out things like empty-result behavior for platforms with partial reporting or whether LinkedIn page vs. member distinction requires a separate account selection, minor gaps only.

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 description says nothing about period, start_date/end_date, or the platform enum. The schema carries the full parameter burden, 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 opens with the user questions it answers and names the exact resource (follower demographics) and dimensions returned per platform. It is clearly distinguishable from siblings like get_follower_history (counts) or get_analytics_summary (performance) without needing their 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 gives an explicit when-not condition: other platforms and LinkedIn member profiles don't expose this data, which prevents wasted calls. It does not name the alternative tool to use for follower counts or audience growth, so the routing advice is one-directional rather than complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only.' merely restates that. It adds real value with the timezone caveat and the historical-basis framing, but says nothing about what happens with insufficient post history, how 'performed best' is measured, or the cost of long date ranges.

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: the first front-loads the intent via user-voice questions, the second delivers the return shape and timezone qualifier. Nothing is wasted and the important scoping detail comes before the trailing 'Read-only.'

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 analysis tool with a fully documented schema and no output schema, the description covers purpose, scope, and return shape adequately. The remaining gap is the definition of 'performed best' (which engagement signal) and empty-result behavior, which an agent would still have to guess.

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 all five parameters including the period/start_date interplay are already documented in the schema. The description's only added parameter context is that returned slots are in the user's timezone, which does not extend to the date-range parameters. 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 resource and output: 'day-of-week and hour slots (in the user's timezone) where posts have historically performed best' for a given platform. The question-phrasings ('when should I post?') map directly onto the tool's intent, making it distinguishable from analytics siblings like get_analytics_summary or get_format_performance.

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 three example questions make the use case obvious and the 'for a platform' scoping tells the agent to supply a network. It stops short of naming any alternative or exclusion (e.g., versus get_analytics_summary or the queue tools get_queue_slots/add_queue_times), so the agent must infer the boundary itself.

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, non-destructive, closed-world), and the description adds real behavioral context on top: the data is workspace-scoped to the *active* workspace, includes recent edits/feedback, and is applied server-side by a sibling tool. That server-side-application note is a non-obvious trait that prevents a redundant 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 sentences, each doing distinct work: what it returns, when to call it (with the carve-out), and where to go to change the data. Front-loaded with the payload, 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?

There is no output schema, so the description carries the burden of conveying return contents — and it enumerates them concretely for both the brand half and the voice half. Combined with the routing guidance, an agent has everything needed to decide and call correctly.

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

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

Schema coverage is 100% and the single optional `platform` enum is documented in the schema itself, so the baseline applies. The description never mentions the platform filter, so it adds no meaning beyond the schema — a missed opportunity to say the platform argument narrows which edit history is returned.

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?

It names a specific verb (get) and two concrete resources (workspace brand identity and the user's writing voice), then enumerates the contents of each — positioning, ICP, pillars, signature phrases, openers, avoidances, feedback. That is far more specific than any sibling name suggests, so an agent can tell this apart from `update_voice`, `update_brand`, or `get_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?

It states an explicit ordering rule (call BEFORE composing post copy), an explicit exclusion and its reason (`draft_post` applies this server-side, so skip this tool on that path), and routes to the right mutation tools for changing the data. When-not-to-use is as clear as when-to-use.

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

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

Annotations already declare readOnlyHint=true, so the trailing 'Read-only' adds nothing, but the description goes well beyond them: days before tracking began are omitted and the start date is returned, each series ends with net change, and omitting `account` yields one series per channel. That is real output-shape behavior an agent can't get from the annotations. It stops short of covering rate limits or volume, keeping it at 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?

Front-loaded with the actual data shape, then the disambiguating example questions, then exclusions — a sensible order. Slightly padded by the redundant 'The same numbers as the Analytics page's follower growth chart' and 'Read-only' sentences, which restate rather than add.

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, and the description fully compensates: row granularity, fields, multi-channel series behavior, net-change terminator, and the omitted-days caveat with a start date. An agent has everything needed to call it and interpret 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 baseline would be 3, but the description adds meaning the schema doesn't spell out — notably that omitting `account` across multiple channels produces one series per channel, and that pre-tracking days are dropped rather than zero-filled. The period vs. start_date precedence is covered by the schema, so no extra credit there.

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 ('Daily follower counts'), the exact row shape ('one row per day (date, followers)'), and the platform scope ('LinkedIn only'). It also distinguishes itself from get_analytics_summary for non-LinkedIn platforms, so an agent can route without opening either 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 concrete use-case phrasings in quotes ('how have my followers grown day by day?', 'follower count each day in March') and names the alternative with its selecting condition ('for other platforms use get_analytics_summary'). It also points to start_date/end_date for windows the presets don't cover, so scope decisions are explicit 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so 'Read-only.' merely restates structured data. Nothing is said about minimum data requirements, which engagement metric is used, or how ties/small samples are handled — modest added value for a read-only analytics 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?

Front-loaded with the exact user phrasings an agent would match against, then the one-line verb statement. The trailing 'Read-only.' sentence is redundant with annotations and is the only wasted content.

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

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

With no output schema, an agent still learns that results are format-level and ordered by engagement, which is enough to interpret the response shape. It is silent on which engagement metric is ranked and on sample-size caveats, a minor gap for an analytics tool with full annotation coverage.

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 date/period parameters are documented thoroughly, including override behavior and the 366-day cap. The description adds no parameter guidance of its own beyond 'for a platform', 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 (ranks) and resource (post formats) plus the scoping dimension (by engagement, per platform). The three quoted user questions make it immediately distinguishable from get_analytics_summary, get_post_analytics, or get_best_time_to_post, which cover different analytic axes.

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 example questions give concrete triggers for when this tool is the right pick, which is stronger than most analytics tools. It stops short of naming an alternative or saying when not to use it (e.g., 'for overall account metrics use get_analytics_summary').

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 elsewhere. The description's only added signal is the word "full," implying a complete object rather than a summary row; it says nothing about error behavior for a nonexistent ID or about field 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 zero waste; the verb and scope appear immediately and nothing is padded or 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 trivial one-parameter read tool with rich annotations this is close to adequate, but with no output schema the phrase "full details" leaves the return shape undefined, so the agent cannot anticipate which fields come back.

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 one required parameter with 100% schema description coverage, so the schema already explains `id`. The description's "by ID" merely restates it and adds no format, type, or validity guidance beyond the schema.

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

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

The description states a specific verb and resource ("Get full details of a specific post") and scopes it to a single record by ID, which implicitly separates it from the many list_*/search_posts siblings. It does not name any sibling explicitly, so it falls short of full differentiation.

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

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

Usage is only implied: the agent can infer 'call this when you already have a post ID and need the complete record.' There is no statement of when to prefer it over search_posts or list_posts_with_metrics, and no preconditions or exclusions 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?

Adds real context beyond the readOnlyHint annotation: it discloses what comes back (velocity over time, LinkedIn reaction-type split, per-network metrics such as discussion rate, profile viewers, saves, sends, follows) — valuable since there is no output schema. The trailing 'Read-only' merely restates the annotation, and it says nothing about behavior when a post isn't found or has no data yet.

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 purpose and return shape, then identification mechanics; the example questions are compact and concrete. Slightly padded by the redundant 'Read-only' sentence and by naming individual metric types that could have been summarized as 'all tracked per-network metrics (examples: ...)'.

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 four all-optional parameters, the description is exactly what's needed: it explains how to select a post, what the response contains, and that platform is a modifier rather than a standalone selector. Nothing an agent needs in order 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%, so baseline is 3; the description adds meaning by explaining that post_id, composition_id and latest are alternative identification paths and that platform only narrows `latest` — a constraint the schema hints at but doesn't enforce or explain. All parameters are optional with nothing required, and the description makes clear that one identifier must be chosen.

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?

Opens with a specific verb+resource and scope: full metrics for ONE post, plus time-series velocity. That single-post scope is exactly what separates it from get_analytics_summary and list_posts_with_metrics in the sibling list, so an agent can route 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 concrete user-question triggers ("how did my last post do?") and spells out three distinct identification paths, naming the sibling that supplies each id (list_top_posts, list_drafts). It lacks an explicit 'not for aggregate/account-level reporting — use get_analytics_summary' exclusion, which is the one ambiguity left.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that slots are per-platform and 'next available', implying ordered scheduling state, but it doesn't say what happens when a queue has no open slots, whether timezone matters, or how many slots come back.

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 short, front-loaded sentence with no filler. It is appropriately sized for a simple lookup, though it is so terse that it omits the alternative-tool routing that would make the brevity cost-free.

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 read with annotations and full schema coverage, the description is minimally sufficient. It still lacks the return semantics an agent would want — one slot per platform? earliest available time? empty result behavior? — and there is no output schema to fall back on.

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 single 'platforms' array is documented as 'Platforms to check' with a full enum. The description adds no further parameter meaning beyond confirming the operation is per platform, so baseline 3 applies.

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

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

The description states a specific verb ('Get') and resource ('next available queue slot') with scope ('for each platform'), so an agent knows exactly what the tool returns. It does not, however, distinguish itself from nearby siblings like list_queue_schedule or add_queue_times, which could sound related to queue slot inspection.

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 guidance on when to use this versus list_queue_schedule, add_queue_times, or queue_post. The agent must infer that this is a read-only lookup of open slots, and nothing states prerequisites such as a configured queue or connected accounts.

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 adds useful behavioral scope by enumerating exactly which pipeline counts are returned and explicitly ruling out analytics data.

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

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

The description is short, front-loaded, and wastes no words. It moves from example user intents directly to the included counts and the key exclusion.

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 no-parameter, read-only status tool with no output schema, the description is complete enough. It tells the agent what the tool returns, what it does not return, and when to use it.

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

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

The tool takes zero parameters, so there are no parameter semantics to clarify. Per the baseline for zero-parameter tools, a 4 is appropriate.

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

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

The description states a specific purpose: returning pipeline counts such as drafts, scheduled, posted today, and queue paused status. It explicitly distinguishes itself from analytics tools, so an agent can separate it from get_analytics_summary and list-based siblings.

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

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

It provides concrete trigger phrases ('status', 'summary', 'how many drafts do I have?', 'how many posts are scheduled?') and an explicit exclusion for analytics. The only minor gap is that it does not name a specific alternative tool for analytics, though the exclusion 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?

Far beyond the annotations: it discloses the plan team-member cap, the silent role downgrade (ghostwriter/client/read_only below Business becomes plain member), the all-or-nothing grouping, and the fact that acceptance emails and admits the invitee. It also flags the key failure mode — the agent must not attempt to confirm on the user's behalf because 'no argument does that'. The only nit is a mild tension with readOnlyHint=false, since the tool explicitly claims it modifies nothing; in practice that is conservative annotation rather than a real conflict.

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 core verb and the non-sending caveat, and every paragraph carries real information. It does, however, state the 'sends nothing / do not confirm for them' point three separate times, which is emphatic but costs some density.

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

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

For a single-parameter tool with no output schema, the description covers everything an agent needs: what it returns (one link for the whole list), the permission gate, the role-collapse edge case, and the required post-call behavior. Nothing material is left to inference.

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, and the description earns an extra point by adding semantics the schema cannot express: which roles get silently downgraded on lower plans and that the whole `invites` array produces a single link rather than per-person sends. It does not restate individual fields, which is correct given the rich inline schema.

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

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

The first sentence states a concrete verb and resource — 'Returns a link the user opens to invite one or more people to the account' — and immediately bounds the scope ('one link for the whole list'). A reader can distinguish it from siblings like approve_post or add_queue_times without opening the schema, and the title/description pair is consistent.

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 prerequisites explicitly ('Use `list_members` first to see who is already on the team, and `list_workspaces` for workspace ids') and states the caller restriction ('Account admins only'). It also tells the agent what to do after the call — 'Show them the link and wait' — which is the critical usage instruction for 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=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds value beyond that by disclosing the shape of the result (account IDs, names, which account is currently selected), 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?

Three short sentences, front-loaded with purpose, then return contents, then the natural next action. No filler and nothing repeated from the 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?

For a zero-parameter, read-only listing with no output schema, the description supplies everything needed: what it returns, how the 'selected' flag works, and where to go next. Nothing an agent needs in order 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to compensate for. It correctly implies the call is unscoped and returns everything the authenticated user can see.

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 all accounts the authenticated user has access to') and even names the return fields. It does not, however, distinguish itself from the sibling list_connected_accounts, which an agent could easily confuse with this tool.

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

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

Explicitly routes the agent to the follow-up tool: 'Use select_account to switch to a different account.' That is clear usage context, but there is no guidance on when this is the wrong list to call (e.g. versus list_connected_accounts or list_workspaces).

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, openWorldHint=false, so the safety profile is fully covered. The description adds the useful downstream purpose (numeric id for platform_account_ids) but says nothing about what the returned records contain or how filtering behaves.

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, with the purpose front-loaded ahead of the usage hint. Nothing could be removed 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?

For a one-optional-param list tool with no output schema, the description covers what the tool is for and what the agent should do with the result (extract the numeric id). A brief note on what the output records include would close the last 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% and the single `platform` enum is documented in the schema itself with "Optional: filter to one platform." The description mentions `platform_account_ids`, which is a parameter of a different tool, not this one, so it adds no semantics for the actual parameter — baseline 3.

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 connected social accounts on the current account" — it names the scope explicitly. It doesn't distinguish itself from the sibling list_accounts, which is a plausible point of confusion, 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?

Gives a concrete when-to-use: to obtain the numeric id for `platform_account_ids` when a platform has multiple accounts, with two Twitter accounts as an example. No explicit exclusion or named alternative (e.g. list_accounts) is offered, so it's clear context without 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful default behavior ('defaults to drafts'), but says nothing about ordering, pagination beyond the schema's limit, or what a 'compose post' record contains. Adequate but thin for a read tool whose annotations already carry most of the load.

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, front-loaded sentences with no filler. The wording is efficient, though the second sentence largely duplicates the schema's stated default rather than adding new 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 and a mutation-free, three-parameter tool, the description is minimally sufficient. It still leaves gaps an agent would want filled: what fields come back, result ordering, and how this list differs from the many other list_* siblings.

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 enums fully enumerated and defaults stated, so the schema does the heavy lifting. The description adds only a mild restatement of the status filter and its draft default, which is already in the schema, 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 ('List compose posts') plus the filtering dimension ('filtered by status'), so an agent knows exactly what the tool returns. It does not, however, distinguish itself from closely related siblings such as list_scheduled_posts, list_recent_posts, or search_posts, and the name 'list_drafts' is only partially reconciled by 'defaults to 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?

The description gives no when-to-use or when-not-to-use guidance and never names an alternative. 'Defaults to drafts' is a behavioral default, not a routing rule, so an agent must infer for itself why it would pick this over list_scheduled_posts or list_recent_posts.

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

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

Annotations already declare read-only and non-destructive. The description adds useful context: ordering (newest first), that references are metadata only and never their text, and the permission caveat for listing a teammate's ideas. This goes beyond annotations meaningfully.

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 front-loaded sentences with no waste; each conveys distinct information (purpose, usage, output shape).

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 explains what is shown (tags, references as metadata only), which covers the key return semantics. Pagination is left only to the `limit` parameter description, 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%, so baseline is 3. The description adds value by tying `author` to the same value passed to save_idea and noting the permission requirement, clarifying semantics beyond the schema.

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

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

States a specific verb and resource ('List the user's ideas') plus scope ('on the Ideas tab of the active workspace') and ordering ('newest first'). It is clearly distinguishable from siblings like save_idea and delete_idea.

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 to use it before save_idea to avoid duplicates, and explains when to pass `author` versus omit it. Both the use case and the alternative are named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' adds nothing — but the description goes further by disclosing the admin-only authorization requirement and the fact that the response includes pending invites and seat counts, not just active members. That is genuine behavioral context beyond the structured fields. Only gap: no note on response size/pagination for large accounts.

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 core action, followed by a dense but purpose-built enumeration of returned fields, then the scope note and permission gate. The inline parenthetical is long, and 'Read-only' redundantly restates the annotation, but every other clause carries information an agent cannot get elsewhere.

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 parameters and no output schema, the description must carry the entire burden of telling the agent what comes back — and it does, itemizing members, invites, and seat counts. Auth requirements and scope are also covered, leaving no material gap for correct invocation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The schema coverage is 100% by definition of being empty.

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?

Opens with a specific verb+resource ('List everyone on the account') and then enumerates exactly what is returned: joined members with name/email/role/join date/default-workspace flag/per-workspace roles, pending invites with sender, timestamp and roles, plus remaining seat count. It also scopes the tool ('Covers the whole account, not just the active workspace'), which no sibling name alone conveys.

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 activation condition clearly (account-wide listing vs. a single workspace) and the permission gate ('Account admins only'). It does not name a sibling alternative (e.g., invite_member as the write counterpart, or list_workspaces for workspace scoping), but for a zero-parameter read tool the implied 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful result semantics (only posts with a *pending* review, only those requested by teammates), but doesn't say whether results are ordered, paginated, or what fields come back.

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 definition, zero padding. Slight redundancy between 'asked... to review' and 'pending review', but that repetition reinforces the filter rather than wasting 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?

For a simple, annotated, single-optional-param read tool with no nested objects, the description covers what an agent needs to select and call it. Only minor gaps remain (result ordering, whether an empty list is normal), and no output schema exists to shift that burden.

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 optional parameter (limit) and schema coverage is 100%, so the schema fully documents range and default. The description adds nothing about the limit parameter, which is acceptable at this coverage level but means no value beyond the schema.

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

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

States a specific verb and resource ('List posts') with a precise scope: posts other teammates requested the authenticated user review. This distinguishes it implicitly from the many list_* siblings (list_drafts, list_recent_posts) by the 'pending review' filter, though it never names an alternative.

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 to see what's waiting on their approval' gives a use case, effectively implying this is a review inbox view. It does not mention when to prefer list_drafts, search_posts, or how it pairs with approve_post/send_back_post, leaving alternatives 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/destructiveHint=false, and the closing 'Read-only' is consistent with that. The description goes further with behavior the annotations cannot express: cursor-based pagination ('when the reply ends with a cursor, call again with the same arguments plus that cursor'), page-size limits, and the fact that each row's post_id feeds get_post_analytics and tag_published_post. It stops short of describing metric timing/freshness or how per-platform figures differ, which is why it is not 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?

Front-loaded with purpose and scope before alternatives and pagination mechanics, and nearly every sentence carries operational information. The long parenthetical listing every metric (profile viewers, members reached, saves, sends, follows, lift and clicks) is dense and slightly slows scanning, though it does inform the agent what comes back.

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 7-parameter read tool with no output schema, the description covers the scope, the shape of each row, the pagination contract, and downstream tool chaining — enough to invoke correctly. What is missing is return-volume guidance beyond page size and any note on metric freshness or empty-range behavior.

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 every parameter already carries its own documentation; this sets the baseline at 3. The description adds only marginal semantics — that `author` behaves as on list_top_posts and that cursor must be paired with identical arguments — but leaves the period/start_date override relationship and platform enum behavior 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 plus scope: 'List EVERY published post in a date range, newest first, a page at a time.' It also enumerates the metric payload and explicitly separates itself from list_top_posts, so an agent can distinguish it from list_recent_posts, search_posts and list_top_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?

Gives a concrete when-to-use ('build a full history or export') and names the alternative for the contrasting case ('for the best or worst few, use list_top_posts'). It also pre-empts a likely misuse by stating ranges may exceed a year, removing the ambiguity that might push an agent toward period-based windows.

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

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

Beyond the readOnlyHint annotation it discloses useful behavioral details: the workspace scoping, that each entry carries the channel id, the time zone the times are in, and whether the caller is permitted to change the schedule. It does not cover response shape (e.g. list vs map keyed by channel) or ordering, which leaves some ambiguity.

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 dense sentence leads with the resource and payload contents, then the sequencing rule, then the read-only marker. Every clause carries information, though the field enumeration is slightly list-like and could be tightened.

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, one-optional-param tool with no output schema, the description covers scope, returned fields, ordering precondition and safety. The only omissions are response structure and how the platform filter interacts with the returned channel list.

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 optional platform parameter has full schema description coverage plus an enum, so the schema does the work. The description never mentions the platform filter, adding nothing beyond what the schema already states, which places it 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?

States a specific verb and resource ('List the weekly posting schedule (queue times) of each channel on this workspace') and enumerates the returned fields, so an agent knows exactly what data it gets. It does not explicitly differentiate itself from nearby siblings such as get_queue_slots or list_scheduled_posts, which are the most likely confusions.

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: 'Call this before add_queue_times or remove_queue_times', naming concrete alternatives and the ordering that selects them. It stops short of saying when this is the wrong tool versus get_queue_slots or list_scheduled_posts, so there is no exclusion 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 carry readOnlyHint=true and destructiveHint=false, so "Read-only" is redundant, but "Carries NO performance numbers" adds real payload-shape context not present in structured fields. It doesn't mention whether results are ordered newest-first or what fields are returned, which would be the remaining gap.

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 user intent, then the scope, then the alternative. Every sentence earns its place with zero repetition or filler.

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

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

For a single-optional-param, read-only list tool with no output schema, the definition covers intent, scope, safety and routing. Nothing an agent needs in order 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?

There is exactly one optional parameter and schema coverage is 100%, with the default (5) and max (10) already documented in the schema. The description adds no meaning about how limit interacts with the result set, 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 concrete verb+resource framed as the user question it answers ("what did I post recently?") and pins the payload scope: "Lists what went out and where." It explicitly distinguishes itself from analytics siblings, so an agent can route 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?

Names both the use case (recent post history) and the exclusion ("Carries NO performance numbers"), then redirects to the correct alternatives: get_post_analytics or list_top_posts. This resolves the single most likely sibling ambiguity.

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 adds that results include post times and exclude performance metrics, but it does not describe pagination, timezone handling, or empty-result 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?

Three short sentences with the primary use cases front-loaded, then the result type and scope constraint. No filler or redundant explanation.

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-parameter list tool with annotations covering safety, the description supplies enough context: what is returned and what is excluded. Minor gaps like pagination or timezone behavior are not material 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 coverage is 100%, and the single window enum is fully described in the schema. The description echoes the same time windows in natural-language questions but adds no syntax or default-value 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 and resource: lists scheduled posts with their times. It distinguishes the tool from analytics-oriented siblings by saying it is read-only and has no performance numbers, though it does not explicitly name alternatives.

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

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

Frames usage through concrete user questions such as "what's going out today?" and "what's scheduled this week?", which clearly maps to the tool's window parameter. It does not explicitly say when to use a different sibling 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 read-only/non-destructive profile, yet the description still adds the default ranking metric, cross-platform default scope, and the returned fields (id, stats, snippet, link). It repeats "Read-only" from annotations but contributes genuine behavioral defaults beyond them.

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

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

Front-loaded with the question examples, then labeled sections ("WHOSE POSTS") make it scannable. The author-routing block is somewhat verbose for what it says, but each sentence resolves a real ambiguity.

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?

Eight all-optional parameters and no output schema, so the description carries the burden of stating defaults, return shape, and the "me" vs name vs workspace ambiguity — all of which it does. 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 coverage is 100%, so the baseline is 3, but the description goes further by mapping natural-language cues onto `author` and explaining the platform-omission semantics in prose. The remaining parameters (period vs start/end, limit) are left entirely 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?

Opens with a specific verb+resource ("Rank recent posts") and anchors it with four concrete user questions, which immediately separates ranking from the many `list_*` siblings. An agent can tell this is a ranked-best/worst query, not a chronological listing.

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 routes the ambiguous cases: "my"/"mine" -> author: "me", a name -> that name, "our"/"team"/no one -> omit author, with an explicit warning not to assume "my" means workspace. Also states order: bottom for worst-performers and when to omit vs pass platform.

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 safety is covered. The description adds genuinely new context beyond them: the agency account model of one workspace per client, what each workspace contains (drafts, connected channels, brand, analytics), and that the active workspace is identified in the 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?

Three short sentences, front-loaded with the verb and resource, followed by the domain model and then the call-ordering instruction. Every sentence adds information an agent needs and none 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?

No output schema exists, so the description carries the burden of hinting at returns, and it does: it promises the list of accessible workspaces plus which one is currently active. Combined with zero parameters and annotated read-only behavior, an agent has everything needed to call it 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 no parameter semantics to document and the baseline is 4. Nothing in the description is needed to clarify 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 ("List") and resource ("workspaces (clients) on this account") plus the scope constraint that only workspaces the user can work in are returned. It also disambiguates from the sibling select_workspace by defining this as the read that precedes that selection.

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 select_workspace so you can name a real one." That is a concrete prerequisite relationship with a named alternative, 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 only say this is a non-read-only, non-destructive, closed-world mutation. The description goes far beyond: tags are matched by name or created in the target, the lane is cleared, author and reviewers are granted access to the new workspace, account admins only, and the move is reversible. It also discloses the failure mode for channel mismatch — exactly the side-effect detail annotations cannot 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?

Six short sentences, purpose front-loaded, then mechanics, then constraints. Every sentence carries distinct operational information; none restates the name or the 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?

No output schema exists, yet the description covers preconditions (draft only, admin only), side effects (tags, lane, access grants), failure behavior, and reversibility. Nothing an agent needs before invoking 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 the baseline is 3. The description earns above that by clarifying that post_id resolves in any workspace, not just the active one — a non-obvious lookup scope — and by pointing at list_workspaces for the workspace argument.

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 with scope: 'Move a draft to another workspace (client) on this account.' It also distinguishes the operation from anything a sibling does by noting it locates the post across workspaces rather than in the active one.

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

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

Explicit when-to-use ('for a post saved in the wrong one'), an explicit exclusion ('Only drafts move: cancel a scheduled post first' — naming the cancel_post sibling's role), and a refusal condition ('A post set to go out on a channel that isn't in the new workspace is refused').

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 and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: scheduled posts are held and 'wait' rather than being cancelled or deleted, which tells the agent the operation is non-destructive to queue contents.

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, action front-loaded, with the consequence of the action second. Nothing is wasted and nothing 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 parameters, no output schema, and annotations covering the mutation/safety profile, the description supplies what an agent needs to call it correctly. It could go one step further and state scope (workspace/account-wide) and that resume_queue reverses it, but the core is 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.

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 (Pause) and resource (the publishing queue) and immediately describes the effect. It is effectively distinguishable from the sibling resume_queue by antonym, 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 implied: use this to stop scheduled posts from going out. There is no explicit statement of when not to use it, whether it is reversible, or that resume_queue is the counterpart for undoing 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?

Beyond the destructive/openWorld annotations, it discloses that publishing is irreversible, that it goes out under the user's own name, that the actual publish happens on a confirmation page the user must click, and that the page names the target account. This is exactly the behavioral context an agent needs before invoking.

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 critical constraint is front-loaded and the safety instructions are tight, but the 'returns a link the user opens to publish' idea is restated twice, which is mild redundancy (albeit deliberate emphasis for an irreversible action).

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

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

There is no output schema, and the description covers the return value (a link), the required human step, irreversibility, the posting identity, and the multi-account targeting case. Nothing needed 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%, so the schema already documents id, platforms, and platform_account_ids, and the baseline would be 3. The description adds real meaning for platform_account_ids by explaining the multi-account-per-platform case and that the confirmation page surfaces the chosen account, which the schema does not convey.

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 precise verb and resource: it returns a link the user opens to publish a draft themselves, and it explicitly corrects the misleading tool name by saying it does NOT publish over MCP. An agent immediately knows what it gets back. It does not name sibling tools (e.g. approve_post, schedule_post) to differentiate, which keeps it just below 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?

It gives explicit when-to-use behavior ('Show them the link and wait. Do not try to confirm on their behalf'), warns that inventing a confirmation argument is ignored, and notes the alternate channel (SMS/WhatsApp `publish 123`) where direct publishing applies. It also tells the agent when to supply platform_account_ids.

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 and destructiveHint=false, so the additive mutation nature is known. The description adds valuable behavioral context: the tool uses the configured posting schedule, refuses a channel with no times and adds nothing for it, and defaults to the first connected account unless platform_account_ids is passed. It stops short of describing return values or partial-failure behavior across multiple channels.

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

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

The description is front-loaded with the core action and follows with tightly scoped prerequisites and targeting behavior. Every sentence adds useful information, and there is no repetition or filler.

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

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

For a mutation tool with four parameters including a nested object, the description covers purpose, operational constraint, prerequisite, and account targeting. It omits potential return values or error handling beyond the no-posting-times case, but with no output schema and strong annotations, 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?

Schema coverage is 100%, so the schema already documents each parameter thoroughly. The description adds meaning beyond the schema by explaining the default account selection behavior for platform_account_ids and the prerequisite for Instagram media on the platforms parameter, though it does not cover variance_minutes or all parameter nuances.

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

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

The description opens with a specific verb and resource: 'Add a post to the next available queue slot.' It immediately distinguishes this from alternative scheduling tools by noting it uses the configured posting schedule and routes to add_queue_times when no schedule exists. An agent can tell it apart from schedule_post or add_queue_times 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?

It explicitly states a prerequisite (channel with no posting times is refused; use add_queue_times first) and gives a clear condition for platform_account_ids. However, it does not compare directly against siblings like schedule_post or publish_post, so the when-to-use versus those alternatives 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 destructiveHint=true and readOnlyHint=false, and the description adds meaningful context beyond them: the default scope is all days, and 'Posts already queued keep their times' clarifies the deletion is non-retroactive. It omits error behavior for times not present in the schedule, which would be useful for 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?

Four short sentences, front-loaded with the action and scope, then the default behavior, format, and side effect. No filler; every sentence carries decision-relevant information.

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

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

Given a destructive mutation with no output schema, the description covers what is removed, from which scope, in what format, and what is left untouched. Minor gap: no mention of what happens if a specified time doesn't exist in the schedule or how multi-account workspaces are resolved.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value: the times are '24-hour HH:MM in the workspace's posting time zone' (schema only says 24-hour HH:MM), and the 'one channel' framing explains why platform/platform_account_ids matter. The days-omission behavior is restated with a useful analogy rather than just repeated.

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 ('Remove posting times from one channel's weekly queue schedule') with explicit scope ('one channel', 'weekly'). It is immediately distinguishable from the inverse sibling add_queue_times and from list_queue_schedule.

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 key decision point: omitting `days` removes the time from every day, analogous to the delete button on the Posting Schedule page. It doesn't explicitly name add_queue_times as the alternative, but the inverse relationship is clear enough for an agent to route correctly.

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

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

Annotations only say this is a non-read-only, non-destructive, open-world mutation. The description adds real behavior: required reviewers hard-block publishing, optional reviewers are FYI-only, and the workspace may refuse reviewers outside it by name. That last sentence in particular tells the agent how failures surface, which annotations never could.

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?

Five short sentences, front-loaded with the core action and followed by the blocking rule, the prerequisite, the scheduling option, and the permission caveat. Nothing repeats the name or title and no sentence is 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 mutation tool with no output schema and only four parameters, the agent has what it needs: when it can be called, what the reviewer flags do, how scheduling interacts with approval, and how permission rejections appear. Return payload detail is the only gap and 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%, so the schema already documents post_id, reviewers, note, and scheduled_at, and the description mostly restates the required-vs-optional reviewer distinction found in the schema. It adds only a little beyond that (scheduling is optional and tied to approval), 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 first sentence gives a specific verb (request review) and resource (a draft) and the second explains the outcome (blocking publishing). It is clearly distinguishable from siblings like approve_post or list_posts_awaiting_my_review, which sit on the other side of the review lifecycle.

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?

Prerequisites are explicit: the post must already be a draft, and the description names save_draft as the tool to call first. It also describes the two reviewer modes and their consequences, which tells the agent which configuration to pick rather than leaving it 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=false, destructiveHint=false, openWorldHint=true, so the safety profile is structured. The description adds the piece annotations can't: the downstream consequence that queued posts will actually be published to external channels once resumed, which is the key risk-relevant 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 action and resource, with the outcome as a trailing clause. Nothing is padded or 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 no-parameter, no-output-schema state toggle this is nearly sufficient. It could add what happens if the queue is not paused, or that queue slots/timing are preserved, but nothing essential 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter hints are present.

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 ('Resume') and resource ('paused publishing queue') plus the concrete effect ('scheduled posts go out again'), which cleanly separates it from pause_queue and from queue_post/schedule_post. It stops short of naming a sibling or explicit counterpart, so 4 rather than 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?

The precondition is stated in the description itself: the queue must be 'paused', and use is to make scheduled posts publish again. There is no explicit 'do not use when...' or naming of the inverse tool (pause_queue), 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 declare the safety profile (readOnly=false, destructive=false); the description adds real behavioral context beyond them: media and existing schedule are preserved, channel-specific tailored copy is untouched, the revision runs the voice engine server-side, and replaced words are recoverable from version history in DemandBird. That last point is the key reversibility disclosure for a mutation 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?

Purpose and the anti-pattern warning are front-loaded, then preservation guarantees, then recoverability. Each sentence carries distinct information — no restatement of the title or the 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 non-destructive mutation with no output schema, the description covers what an agent must know: which post is affected, what is preserved, what is recoverable, and which sibling not to use. There is no material gap that would cause a misinvocation.

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 id, feedback, platform, and draft_anyway thoroughly. The description adds only indirect semantic context (the revision touches the shared draft, not per-channel tailored copy), which helps interpret the platform parameter but is not stated as parameter guidance. 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 ('Apply the user's feedback to an EXISTING draft') and pins the outcome ('save the revision onto the SAME post'). It explicitly distinguishes itself from the nearest sibling, draft_post, so an agent can route correctly without inspecting 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 both sides of the routing decision: use this 'every time the user reacts to a draft you already produced', with concrete trigger phrases, and 'Do NOT call draft_post again to act on feedback', including the consequence of getting it wrong (a second draft plus an orphaned first draft with its images). Nothing 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 only declare readOnly/destructive/openWorld flags; the description adds the substantive behaviors the agent actually needs: drafts never publish, a penciled time holds the slot without scheduling, only privileged users may save as another author, nonexistent tags fail unless the user can manage tags, and invalid platform_account_ids cause the whole save to fail. That is exactly the value-add beyond the annotation block.

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 selection-critical content is front-loaded in the first two sentences, and the negative instruction follows before any parameter detail. It runs long and repeats points already carried by the schema ("Drafts never post. A penciled time only holds the slot" appears in both places), which is wasted space against a 100%-covered 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 an 11-parameter, deeply nested, non-read-only tool with only flag-level annotations, the description covers the gaps that would actually cause a bad call: permission gates, platform content requirements (YouTube video, Instagram media, PDF LinkedIn-only), the interaction with scheduling tools, and the exclusivity of first_comment vs first_comments. No output schema exists, but nothing about the return value would change how the agent invokes it.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by giving usage triggers rather than definitions: pass `author` when filing a teammate's post, `platform_account_ids` when a workspace has two accounts on one platform, `channel_copies` instead of a second post. It still largely restates what the schema already says in depth rather than adding new semantics, so it does not reach 5.

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

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

States a specific verb and resource ("Save the user's own content as a draft") and immediately draws the boundary that matters: no AI generation, text stored verbatim. It names the sibling it is not (draft_post) and the prerequisite it may need (get_brand_voice), so an agent can pick it without opening another 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?

Explicit when-to-use ("when the user provides explicit text they want saved"), explicit when-not ("If YOU wrote the copy... use draft_post instead" or fetch brand voice first), and an explicit prohibition ("Do NOT call queue_post or schedule_post unless explicitly asked"). Nothing about tool 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 declare the write profile (readOnlyHint=false, destructiveHint=false), so the description's real contribution is the atomicity guarantee ('All the ideas in one call are saved together, or none are') and the explicit 'No AI, the text is stored verbatim'. It also discloses the permission gate on author. It does not discuss failure modes for oversized content or rate limits, which keeps it off 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?

One dense paragraph, front-loaded with the purpose before the routing guidance. Nearly every sentence carries non-derivable information (atomicity, author scoping, references-vs-content), though the closing tags sentence and the audience caveat partially restate schema text and 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 2-parameter tool with a nested idea object and no output schema, the description covers the things an agent would otherwise get wrong: workspace selection order, dedupe via list_ideas, verbatim/no-AI storage, cross-idea atomicity, and where source material belongs. What it lacks (return shape, tag-creation failure reply) is already covered by the schema's parameter descriptions.

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 meaning the schema does not: author is scoped to the whole call ('one author per call, applied to every idea in it'), and the content/references split is given a rationale ('references are stored alongside it and carried over to the post when the idea is drafted' vs the idea text being what gets drafted). Tags' persistence through drafting is likewise stated beyond the schema's matching rules.

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 one or more ideas to the Ideas tab of the active workspace') and immediately disambiguates what an idea is ('thoughts that are not posts yet'). It explicitly contrasts with the nearest sibling, save_draft, so an agent can pick between them 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?

Names the alternative ('Use this, not save_draft, when moving a backlog of ideas in from another tool') plus the prerequisite ordering: call select_workspace first to pick the client, and list_ideas to avoid duplicates. The author case ('When the ideas belong to a teammate, pass their name as author') is an additional conditional rule with its own trigger.

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

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

Discloses non-obvious behavior the annotations cannot convey: stored times are jittered by up to half the variance window, the pencil is cleared when a penciled time is consumed, drafts never post, and the response reports when jitter occurred. These are exactly the side effects an agent needs before committing a schedule.

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?

Purpose is front-loaded in the first sentence and the rest is a dense run of edge-case rules with little waste. The pencil/penciled-draft idea is restated across three sentences, slightly more repetition than necessary, but 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, and the description covers the important return signal (the reply reports jitter) plus the draft-scheduling path and cross-tool prerequisite (add media via update_draft for Instagram). The only missing piece is any note on what happens on partial platform failure, which is a minor gap for an open-world scheduling call.

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, and the description earns a step above it by explaining the targeting rule for platform_account_ids (falls back to the first connected account) and the practical meaning of variance_minutes as an override. It adds real interpretive value rather than restating 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?

Opens with a specific verb and resource: scheduling a post for a date/time across named platforms. It is distinguishable from draft-only tools and from queue-based ones by the explicit 'scheduled_at' semantics, but it never names the adjacent siblings (queue_post, publish_post, draft_post), so the 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?

Gives concrete conditional guidance: use platform_account_ids when multiple accounts exist for a platform, pass variance_minutes: 0 when the user means an exact time, and omit scheduled_at only for penciled drafts. It lacks any explicit statement of when to prefer this over queue_post or publish_post, which is the main 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 cover the safety profile, but the description adds real behavior beyond them: conjunctive matching over every word, a five-word ceiling, newest-first ordering, and exactly what each result carries (post_id, date, snippet, headline numbers, link). It doesn't say what happens when a query exceeds five words or how the 25-result cap interacts with result paging.

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 purpose, then search semantics, then return shape, with no filler sentences. The three quoted example queries and the LinkedIn/off-platform scope clause make it longer than strictly necessary, though each still contributes.

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?

Six parameters with one required, no output schema, so the description must carry return information, and it does: result ordering, per-match fields, and how post_id feeds downstream tools. Search scope, defaults, and matching rules are all present, leaving nothing an agent needs in order to call 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 description coverage is 100%, so the per-parameter semantics (author, platform enum, date bounds, limit) are already fully documented. The description adds only a little on top, namely case-insensitivity and the five-word cap on `query` and the "no dates means all time" default. Baseline 3 is appropriate when the schema carries this much weight.

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 ("Find published posts by what they say") and immediately bounds the corpus: every post on the workspace's channels, including LinkedIn imports and posts made outside DemandBird. The example phrasings and the follow-up pointer to get_post_analytics/tag_published_post make it distinguishable from list_posts, list_recent_posts, and get_post 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?

Gives concrete when-to-use triggers via three natural-language examples and a clear usage rule ("use a few distinctive words, not a sentence"), plus the default that omitting dates searches all time. It does not explicitly exclude the sibling listing tools (list_posts, list_recent_posts) for cases like browsing without a keyword, so the agent must infer that boundary.

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

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

Annotations already declare readOnlyHint=false/destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context: this mutates session state so every later tool call operates on the new account. It doesn't state what happens with an invalid ID or whether the switch persists across sessions.

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 action, then its consequence, then the prerequisite. No 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?

For a single-parameter, no-output-schema tool with annotations, this covers the essentials: what it does, its state effect, and how to get valid IDs. The only real gap is disambiguation from select_workspace and failure behavior on bad 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 coverage is 100% and the account_id property already documents the 'acct_xxx' or numeric formats. The description only points to list_accounts as the source of valid IDs, which is mildly useful but adds little 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?

Clear specific verb+resource: 'Switch to a different account' and states the scope effect (all subsequent calls). However, it never distinguishes itself from the sibling select_workspace, leaving the agent to guess how account vs. workspace selection differ.

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 prerequisite: 'Use list_accounts first to see available accounts and their IDs.' It does not say when NOT to use this tool or how it relates to select_workspace, so there is no exclusion 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 only declare the mutation-safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description supplies the genuinely important behavior the annotations cannot: the selection is stateful and persists across later calls and messages until changed, and it re-scopes drafts, schedules, channels and analytics. That is exactly the hidden side effect an agent must know before calling.

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 the action, then consequences, then the usage rule and the exclusion. Four compact sentences, each carrying a distinct piece of decision-relevant information with no repetition.

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

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

Single-parameter stateful tool with no output schema; the description covers what changes, how long it lasts, and the main misuse case. Nothing an agent needs in order 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% and the schema already documents the single 'workspace' parameter, including accepted forms (name or numeric id) and the source ('as returned by list_workspaces'). The description adds nothing about the parameter, 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 ('Switch which workspace (client) you are working in') and immediately clarifies the scope of the change. An agent can distinguish it from draft_post and select_account 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?

Gives explicit trigger phrases ('switch to Acme', 'work on Acme now'), an explicit exclusion ('Do NOT use it to write something FOR a client while staying where you are'), and names the correct alternative (draft_post with the topic). This is the when/when-not/alternative trifecta.

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 the actual mechanism: the tool does not perform the action, it returns a link the user opens to review the copy and press Send back themselves. It also flags that the note reaches the author verbatim, which is a real behavioral consequence the agent must respect.

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 is front-loaded in the first sentence and nothing is irrelevant. The middle sentence partly restates the link mechanism already introduced ('returns a link they open ... press Send back themselves'), which is mild redundancy even if it reinforces user agency.

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 explains the return value (a link) and the human-in-the-loop handoff, and both required parameters are fully documented in the schema. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description adds genuine meaning by stating the note reaches the author verbatim and should be written as the user said it, which constrains how the agent should fill that parameter. It adds nothing extra for post_id, which the schema already covers.

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 ('Returns a link ... to send a post back to its author with a note') and immediately frames it as 'the opposite verdict to approve_post', so the agent can distinguish it from the closest sibling without opening either 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 positions the tool relative to approve_post (opposite verdict) and scopes it to 'a post the user is reviewing', which tells the agent when to reach for it. It stops short of naming exclusions or the discovery step (e.g. list_posts_awaiting_my_review), so not quite 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 and destructiveHint=false, so the safety profile is known. "Saves nothing" adds genuinely useful behavioral context beyond that: the suggestion is ephemeral and must be applied by a separate write tool, which tells the agent not to expect persistence. It stops short of explaining where suggestions come from (model? brand voice?) or how they vary between calls.

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, front-loaded sentences with zero waste. The unusual "Saves nothing" clause is placed second where it reads as a caveat rather than burying the main purpose.

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

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

There is no output schema, so the description is the only place the caller could learn the shape of the result (a hashtag list plus a replacement opening line?) and it doesn't say. For a simple read-only suggestion tool with a trivial one-param schema the core need is met, but the return contract is left to inference.

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% on a single parameter, and the schema already documents that id defaults to the most recently updated draft. The description only implies the draft target via "for a draft" and adds no syntax or fallback detail of its own, so 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?

Specific verb ("Suggest") plus two concrete outputs (hashtags and an alternative opening line) scoped to "a draft". An agent can tell it apart from nearby siblings like revise_draft or draft_variations, though the description never names those alternatives 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: it operates on a draft, and the schema note says the id defaults to the most recently updated draft. There is no explicit "use when" framing, no statement about when to prefer revise_draft or tailor_draft, and no prerequisites 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 this is a mutation with destructiveHint=true, so the safety profile is known. The description adds valuable behavioral context beyond annotations: the tool reaches every post in the Analytics tab, including imported/outside posts, and tags are shared across every channel for DemandBird-written posts. It does not restate that tags are replaced (schema covers that) but adds meaningful reach and propagation semantics.

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

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

The description is front-loaded with the core purpose, then adds reach, usage guidance, and channel propagation in separate sentences. It is appropriately sized for a mutation tool, though the opening clause could be tightened slightly.

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 needn't explain return values. For a two-parameter mutation tool with full schema coverage and annotations covering safety, the description provides enough context about reach, alternatives, and cross-channel behavior. A minor gap is the lack of explicit guidance on when to use update_draft instead, but the implication is clear.

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 fully documented in the schema, including the replacement behavior for tags and the source of post_id. The description only repeats that post_id comes from list_top_posts and get_post_analytics, adding little beyond the schema. Baseline 3 is appropriate when the schema carries the semantic load.

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 (Set the tags) and resource (a post that is already published), and immediately distinguishes it from update_draft by noting that update_draft cannot reach imported or externally posted items. An agent can tell this tool apart from siblings like update_draft or save_draft 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?

It gives clear context: use it to label past posts the way they were labelled in the source tool, and it explicitly covers posts shown in the Analytics tab including imported ones. It does not explicitly say when to prefer update_draft for drafts, but the contrast with update_draft implies the boundary.

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

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

Annotations declare the safety profile (readOnlyHint false, destructiveHint false, openWorldHint false), and the description adds real behavioral context: the voice engine runs, channel_copy preserves the post's media and schedule and publishes that text on that channel, and the original remains restorable in version history. It doesn't say what the call returns or whether the rewrite overwrites anything visible immediately.

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?

Purpose is front-loaded, followed by example utterances and then the save_as decision rule. Every sentence carries information, though the version-history sentence at the end is the least load-bearing and the examples duplicate phrasing an agent could infer.

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

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

For a 3-parameter mutation with no output schema, the description covers the main decision (channel_copy vs new_draft) and its side effects well. The notable gap is that it never says what comes back — the rewritten text, an id, or a draft object — which matters when chaining to a publish step.

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 would be 3, but the description adds meaning beyond the schema for save_as — that channel_copy keeps media and schedule, publishes on that channel, and stays in version history. The platform parameter is only elaborated via the Instagram constraint already 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 ("Rewrite an existing draft") plus a target dimension ("for a specific platform") and adds that the voice engine runs. It does not explicitly distinguish itself from near-siblings like revise_draft, update_draft, or draft_variations, so the 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?

Gives concrete trigger phrases ("rewrite 123 for Twitter", "make that work on LinkedIn") and an explicit when-to-use rule for save_as: channel_copy ("when the user wants one post on several channels with different text"), plus the default behavior. It stops short of naming alternative tools for adjacent jobs such as revising or updating a draft.

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

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

The annotations already flag this as destructive and not read-only. The description adds important behavior beyond that: each passed field replaces existing content, omitted fields are kept, an empty string clears a field, values are stored as given with no AI transformation, and the change applies to the workspace chosen via select_workspace with the reply naming it.

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

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

The description is front-loaded with the core action and then layers in usage triggers, field replacement semantics, workspace scoping, and the sibling alternative. Every sentence carries useful information, though it is somewhat longer than strictly necessary for a two-field update tool.

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

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

There is no output schema, but the description explains what the tool changes, how omitted and empty fields behave, which workspace is affected, that values are stored verbatim, and where to go for a related but different need. An agent has everything required to call it 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 schema already defines both parameters and their 2000-character limits. The description adds genuinely useful semantics the schema does not convey: omission preserves the existing value and an empty string explicitly clears it. It stops short of explaining format expectations beyond that, but the added replacement semantics are substantive.

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 (change the active workspace's brand identity) and names the exact fields affected, positioning and ICP. It also distinguishes itself from the sibling update_voice by pointing to that tool for personal writing style.

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 trigger scenarios with an example user utterance ('our audience is now CFOs, not founders') and names the alternative tool (update_voice) with the condition that selects it. The agent knows when to use this versus a sibling without needing to infer.

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

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

Annotations only declare non-read-only, non-destructive, closed-world. The description adds substantive behavior: schedule is preserved, content saved verbatim with no AI pass, edits preserved in version history and restorable, per-channel copies are untouched by a shared-content edit, and a penciled time holds the slot without scheduling. That is exactly the context annotations cannot carry.

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 editability rules before the parameter-by-parameter guidance. Dense but every clause carries a constraint or an alternative. Slightly overlong as one unbroken block; splitting the per-parameter guidance would improve scanability.

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 14-parameter mutation tool with nested objects and no output schema, the description covers editability limits, side effects, scheduling interactions, workflow-stage rules, and failure modes. Nothing an agent needs 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 coverage is already 100%, so the baseline is 3; the description earns above that by explaining cross-parameter interactions the schema treats in isolation — content vs channel_copies, first_comment vs first_comments mutual exclusivity, stage_note being required for on_hold, and penciled_at vs schedule_post. Small gap: it says less about platforms/images than the schema does, relying on the schema there.

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?

Opens with a specific verb and resource set ("Update a post's content, media, platforms and/or tags") and immediately scopes which post states are editable. It explicitly distinguishes itself from schedule_post, queue_post, and tag_published_post, so an agent can route correctly without opening sibling 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?

States when-not (already publishing or posted cannot be edited), when-to-use alternatives (schedule_post/queue_post to change timing, get_brand_voice before rewriting copy), and the exact condition for channel_copies vs a second post. Every branch of the decision is spelled out.

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 say destructive/non-read-only; the description goes well beyond by disclosing whole-value replacement, the list-replacement rule, durability across re-learning, the reset escape hatch, no-AI raw storage, and all-or-nothing atomicity of a call. Those are precisely the destructive-behavior details an agent needs before invoking.

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 purpose and trigger examples, then constraints. It is dense but nearly every sentence carries a distinct operational rule; only the repeated reset/wording around durability is slightly 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?

Covers the high-risk semantics for a destructive single-parameter mutation: atomicity, replacement semantics, persistence, reset, and scope limits. Only the return value/confirmation shape is left unstated, which is a minor gap absent an output schema.

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

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

Schema coverage is 100%, so field types and the voice_signature word vocabulary are already documented. The description adds the semantic that matters: each edit replaces the entire field value, so lists must be sent complete. It does not re-explain per-field enum values, which is fine since the schema does.

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 + scope: changes the caller's own personal writing voice, equivalent to Settings > Voice. It explicitly carves out what it is not (a teammate's or a client workspace's voice) and routes workspace positioning to update_brand.

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 utterances the agent can pattern-match against ("I never use the word synergy", "I work with Dana now") plus named alternatives: get_brand_voice to read current state and update_brand for workspace-level positioning.

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), so the description carries the real burden and does: it discloses that the call does not upload the bytes itself but returns a presigned S3 URL plus a curl command to run locally, then hands back an s3_key. It also states the 100 MB ceiling, the supported MIME families, and the PDF-to-LinkedIn-document behavior — none of which is inferable 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?

Front-loads the routing decision, then the reason, then the mechanics, then limits and the PDF edge case. Every sentence carries operational information; nothing is repeated from the name 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 output schema, the description correctly explains the return shape (presigned URL + curl command + s3_key) and the downstream consumption pattern, plus size and format limits. Minor gaps remain: presigned URL expiry/retry behavior and whether the uploaded asset is scoped to an account or workspace before draft_post uses it.

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

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

Schema coverage is 100% for the two parameters (filename, content_type), so the schema already explains them including extension-based inference. The description's format list ('JPEG, PNG, GIF, WebP…') loosely constrains content_type but adds no syntax, defaults, or naming conventions 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 and resource ('attaching images, videos or a PDF to a post') and explicitly positions itself as the PRIMARY path versus the two named alternatives (inline base64, file_path). An agent can distinguish it from generate_image or attach_reference 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?

Gives an explicit selection rule ('Call this FIRST for any image beyond a thumbnail'), explains why the alternatives fail (parameter size limit, remote MCP server), and names the downstream tools and field (draft_post / save_draft / update_draft via `images`). It also carves out the PDF case with its own constraint (LinkedIn only, on its own post).

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