AI social media team for founders: make and publish posts, carousels and short video to LinkedIn, X, Instagram, TikTok, YouTube, Facebook, Threads, Reddit and Bluesky, from any agent. OAuth sign-in, no API key; every draft waits for approval.
Scored across 26 tools
Most tools target clearly distinct resources and actions. The riskiest cluster is posts_create/posts_approve/posts_publish, which all touch publishing, but the descriptions draw sharp lines (create = put on rail, approve = move proposals to schedule, publish = push queued post now). jobs_run vs jobs_continue is a milder overlap but still distinguishable.
Strong, predictable resource_verb snake_case pattern (agents_list, posts_create, jobs_get, brain_write). The main deviations are the bare noun 'me' and a couple of noun-only names, but overall the convention is very consistent.
26 tools is on the heavy side and the 8-tool jobs family is large. The platform genuinely spans multiple sub-domains (agents, brain, characters, jobs, posts, assets), so the breadth is defensible, but it sits at the upper edge of comfortable scope.
Broad lifecycle coverage: posts have create/get/list/approve/dismiss/publish, jobs have create/get/list/brief/continue/run/stop/tail, and brain/agents/characters each have core operations. Minor gaps (e.g. no explicit delete/update for posts or characters) are workaroundable.
The agent roster (the API calls them strategies). Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read (readOnlyHint, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing the required auth scope and the strategies/agents terminology mapping, which is not encoded anywhere in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the resource and immediately followed by the two non-obvious facts (terminology, auth scope). No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param list tool whose annotations carry the safety profile, this covers purpose, naming, and access requirements. Only minor gaps remain, such as pagination or result shape, and no output schema exists to cover them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there is nothing to document and the description correctly avoids inventing parameter 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?
States a specific verb and resource ('The agent roster') and usefully resolves a naming mismatch by noting the API calls agents 'strategies'. It is clearly distinguishable from agents_save/agents_wake, though it doesn't name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Needs the read scope' gives a concrete prerequisite for calling the tool, which is a form of usage guidance, but there is no statement of when to use this versus siblings or any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an agent (no id) or edit one (with id). Setting autoPublishPosts arms publishing without human approval and needs the publish scope; everything else needs write.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The agent id to edit; omit to create. | |
| name | No | Name, up to 60 characters. | |
| prompt | No | The standing brief, up to 4000 characters. | |
| status | No | ||
| planDays | No | Wake days, 0=Sunday. | |
| timezone | No | IANA timezone. | |
| planHours | No | Wake hours. | |
| subreddits | No | Up to 5 subreddits. | |
| connectionIds | No | Accounts to post through; null means all. | |
| monthlyCapCents | No | Monthly spend cap in cents; null = no cap. The studio shows it in credits. | |
| autoPublishPosts | No | DANGEROUS: publish with no human approval. Needs the publish scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds real value beyond them: it discloses which auth scope each path requires and that autoPublishPosts bypasses human approval. It does not cover update semantics (partial vs. full replacement) or what happens to fields omitted on edit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the create/edit split leads, the dangerous option and its scope requirement follow. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with zero required parameters and no output schema, the biggest open question is what happens when editing with only some fields set – merge, replace, or clear – and the description is silent on it. Mode selection and auth are covered, but that mutation-semantics gap keeps this at minimum-viable.
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 91%, so the schema already documents all 11 parameters including the warning on autoPublishPosts. The description's single parameter note largely restates what the schema's own description says, so it adds little beyond 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 split by two clearly defined modes: create when no id, edit when id is supplied. An agent can immediately tell what the tool does, though it never names sibling tools such as agents_list or agents_wake to sharpen 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 explicit conditional usage – omit id to create, include id to edit – plus the permission prerequisite for each path (publish scope for autoPublishPosts, write otherwise). No alternatives or 'when not to use' guidance is offered, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PUBLISH-SCOPED: wake an agent now; it plans and proposes (or with auto-publish, posts) immediately. Returns the conversation it woke into and its web url. Needs the publish scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The agent id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly=false, destructive=true, openWorld=true; the description corroborates and enriches this by spelling out the immediate external side effect ('it plans and proposes (or with auto-publish, posts) immediately') and the required publish scope. It still does not disclose rate limits or whether the wake is idempotent/reversible, so 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?
Three terse, front-loaded clauses lead with the scope label and the action, then behavior, then return values. Nothing is wasted, though the scope tag and 'web url' phrasing are slightly clipped at the cost of readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully covers the return payload (the conversation and its web url), the auth requirement, and the publish branch. A single fully-documented parameter means little else is needed, though the auto-publish trigger condition could be made explicit.
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 (id) and schema description coverage is 100%, so the schema already carries the semantics; the description adds no format, constraint, or ID-source detail beyond what the schema states. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('wake an agent') and immediately qualifies the scope ('PUBLISH-SCOPED'), so it is distinguishable from read-only siblings like agents_list or agents_save. It does not explicitly name an alternative sibling (e.g., jobs_run) for the agent-triggering use case, so it falls short of a full 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?
Says when to use it ('wake an agent now') and names the prerequisite auth scope ('Needs the publish scope'), plus the conditional behavior with auto-publish. No explicit exclusions or named alternatives are given, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The media library: brand uploads and generated media. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 by structured data. The description adds genuinely new context that annotations cannot express: the required read scope, which the agent needs to know before calling. It does not describe return shape or pagination, but the added auth detail is real value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight clauses: the resource identity is front-loaded, followed by the one operational requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list with annotations covering the safety profile, the description is close to sufficient. It does not say anything about the volume or shape of results (no output schema exists to cover this), which is a minor remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no filtering inputs are accepted, consistent with the empty 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?
Names the resource precisely ('the media library: brand uploads and generated media'), which lets an agent distinguish it from sibling list tools like posts_list, characters_list, and platforms_list. The listing action is only implied by the tool name rather than stated in the description, so it stops short of a full verb+resource statement.
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 a precondition ('Needs the read scope') but no guidance on when to prefer this tool over sibling list tools, nor any exclusions. The agent must infer that 'list media assets' is the trigger from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one Brand Memory file. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The file path, like positioning.md. |
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 structurally. The description contributes one extra piece of context beyond that, the required read scope, but says nothing about failure modes (e.g., missing file) or return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse sentences with zero waste; the action is front-loaded and the precondition follows immediately. 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 simple one-param read tool with no output schema the description is close to adequate, but it omits where paths resolve from (brand memory root) and what happens on a nonexistent path. Annotations cover the safety side, so the remaining gap is modest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'path' property already carries a concrete example ('positioning.md'), so the schema does the heavy lifting. The description adds no path syntax, root-directory, or format detail beyond what is structured.
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: 'Read one Brand Memory file.' An agent can distinguish it from brain_write (write) and infer it differs from brain_tree (listing). It does not explicitly name brain_tree as the alternative for browsing multiple files, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Needs the read scope' states a precondition, which is useful, but there is no when-to-use vs when-not guidance and no routing to siblings like brain_tree for browsing or brain_write for mutation. The agent must infer the boundary from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brand Memory's file list with the completion ring. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 genuine value by disclosing the required read scope (auth prerequisite), but says nothing about return format, ordering, or pagination behavior for what is implicitly a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the resource front-loaded and no filler. The only weakness is that "the completion ring" is cryptic rather than wasted, but it is not expanded anywhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description should carry the return-shape burden, yet it never explains what the file list/tree contains or what the "completion ring" signifies. Annotations cover safety, but the agent still lacks enough to know what it will get 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?
The tool takes zero parameters, so the baseline is 4; there is no input semantics for the description to compensate for. No additional parameter meaning is needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource ("Brand Memory's file list") and implies a listing action via the name/title, but never states a verb and the phrase "completion ring" is undefined jargon. An agent can guess this lists files, but the exact nature of a "tree" vs a flat list is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Needs the read scope" is a prerequisite, not guidance on when to use this tool versus siblings like brain_read, brain_write, or other *_list tools. There is no when/when-not and no named alternative, so routing must be inferred from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write one Brand Memory file (.md paths only) - the agent grounds future posts in it. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The file path, must end in .md. | |
| content | Yes | The full file content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, destructive, and closed-world behavior. The description adds genuinely new context: the write-scope auth requirement and the downstream effect of grounding future posts. It does not clarify whether an existing file is overwritten or appended, which is the one meaningful behavioral 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?
A single compact sentence with the action front-loaded and no filler. The parenthetical and trailing clauses make it slightly dense, but every element carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter write tool with no output schema and annotations that cover the safety profile, the description supplies purpose, auth requirement, and downstream effect. Nothing essential to invoking 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 both parameters (path, content) are fully documented in the schema itself. The description only restates the .md path constraint and adds no format, size, or encoding guidance beyond structured data, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Write one Brand Memory file') and adds scoping constraints (single file, .md paths only). The write semantics clearly separate it from siblings brain_read and brain_tree, 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?
Gives clear context for when to use it ('the agent grounds future posts in it') and names an auth prerequisite ('needs the write scope'). It stops short of explicit exclusions or naming brain_read as the read-side alternative, so it is strong 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.
The account's actors: who they are, what their voice is, and which parts are locked. voiceDescription is the casting direction a designed voice was written from - read it before designing another one, and reuse the actor that already fits. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so safety is covered; the description adds the auth requirement ('needs the read scope') and explains the meaning of the `voiceDescription` field. Good added context beyond the structured 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?
Three compact sentences with the resource stated up front, followed by field guidance and then the auth note. Every sentence carries content; structure is slightly loose but far from padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema and full annotation coverage, the description is nearly sufficient: it explains what comes back and the access scope needed. It could go one step further by noting whether results are paginated or 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?
Zero parameters, so there is no parameter semantics to explain; this is the baseline-4 case. The description instead clarifies a return field, which is a bonus rather than a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the account's actors) and enumerates what it returns: identity, voice, and locked parts. It does not explicitly distinguish itself from the sibling characters_voice, which is the one plausible source 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 one concrete directive: read `voiceDescription` before designing another voice and reuse the fitting actor. That implies the usage context but names no alternative sibling or exclusion condition, so the when-to-use guidance is only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SPENDS CREDIT: gives an actor a voice. description designs one from casting direction (kept on the character, so later runs can reuse the actor); sampleMediaKey clones a real voice and requires consent: true - the user's own attestation that they hold the rights. Returns the voice id, a preview clip and what it cost. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| consent | No | Required with sampleMediaKey: the user holds the rights to that voice. | |
| character | Yes | The actor's slug or id (characters_list). | |
| description | No | Casting direction to design the voice from, up to 1000 characters. | |
| sampleMediaKey | No | A 5-10s voice sample already in the account, to clone instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring destructive=true and readOnly=false, the description adds substantial context beyond them: it spends credit, it needs the write scope, the designed voice is kept on the character for reuse in later runs, and cloning requires the user's rights attestation. These are exactly the behavioral facts 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?
Front-loads the highest-risk fact (SPENDS CREDIT) and then splits cleanly into the two parameter paths and the access requirement, plus the return summary. Dense but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the mutation's cost, required scope, consent gating, persistence semantics, and even the return contents despite there being no output schema. For a 4-parameter mutation tool, nothing an agent needs before calling 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 adds real meaning: `description` is casting direction persisted on the character, and `sampleMediaKey` cloning is gated on the `consent` attestation. It also notes the return payload (voice id, preview clip, cost).
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 ('gives an actor a voice') with the added scope that it SPENDS CREDIT. It clearly distinguishes two operating modes — designing from `description` versus cloning from `sampleMediaKey` — so an agent can tell what this tool does and how it differs from siblings like characters_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?
Explains when each mode applies ('description designs one from casting direction' vs 'sampleMediaKey clones a real voice') and the condition `consent: true` for cloning. It does not name an explicit alternative tool or a when-not-to-use condition, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connected social accounts (identity only, no tokens). Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds two pieces of non-structured context: an auth requirement (read scope) and a substantive disclosure that only identity is returned, not tokens — valuable for an agent reasoning about credential exposure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact clauses, each carrying distinct information (what it returns, what it requires), with the resource named first. No filler, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description supplies the key return-content caveat (identity only). It stops short of describing the shape of those identities (IDs, handles, pagination), which is the only remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level semantics are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: connected social accounts, identity data only, with no tokens returned. It is clear what the tool returns, but it never distinguishes itself from the sibling platforms_list, so an agent must guess which of the two lists the accounts it wants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Needs the read scope" is a prerequisite, not usage guidance. There is no statement of when to call this versus alternatives (notably platforms_list) and no exclusions or conditions, leaving selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact context for continuing a conversation: the last messages clipped, an artifact inventory, post statuses, and the web url. Use jobs_get for the full transcript, jobs_continue to reply. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real context: the returned content is deliberately clipped/abbreviated, and it discloses the read-scope auth requirement, which annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The payload contents come first and the sibling routing follows, which is the right front-loading for a read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing the return payload, and it does so by enumerating the bundled fields. Combined with the auth note and sibling routing, nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is exactly one parameter (id), already documented as 'The job id.' The description adds no new syntax or format meaning for the parameter, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool returns: a compact context bundle (clipped last messages, artifact inventory, post statuses, web url). It explicitly contrasts with the two closest siblings, so an agent can distinguish jobs_brief from jobs_get and jobs_continue without inspecting 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?
It names both alternatives with the condition that selects them: jobs_get for the full transcript, jobs_continue to reply. It also states the prerequisite 'Needs the read scope,' so routing and auth requirements are both explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send another message to a job, optionally with files attached - also the way to resume a stuck or failed run with full history. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. | |
| text | Yes | The message, up to 4000 characters. | |
| model | No | Brain for this run: claude-opus-5-5, claude-opus-5, claude-sonnet-5, claude-fable-5-1, gpt-5.6-sol or gpt-6-astra. Absent means the account's default. A model test runs the same goal once per model. | |
| autoRun | No | Execute the plan the moment it is ready instead of pausing for approval. Deliverables still land as proposed drafts. | |
| budgetUsd | No | Budget for this turn, in dollars. | |
| mediaKeys | No | Media keys already in the account (from assets_upload or assets_list) to attach. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so safety profile is partly covered. The description adds real value beyond them: it requires the write scope, and it discloses that resumption preserves full history, which affects how an agent should use it for recovery.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the primary action before the recovery use case and the scope requirement. No filler or redundant restatement of the 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?
Covers purpose, the main secondary use case, attachment capability, and authentication requirement for a 6-parameter mutation tool with no output schema. Nothing essential to a correct invocation is missing, and return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (id, text, model, autoRun, budgetUsd, mediaKeys) are already documented in situ. The description only echoes 'optionally with files attached' (mediaKeys) and adds no format or usage 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?
Specific verb+resource: 'Send another message to a job', with 'another' signalling continuation of an existing job rather than creation. It stands apart from jobs_create and jobs_run implicitly, but no sibling is named explicitly, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use case beyond the obvious reply flow: resuming a stuck or failed run while keeping full history. No exclusions or named alternatives (e.g. jobs_run vs jobs_continue) are offered, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a durable job from a goal, optionally with files attached. The run keeps going server-side; returns the job id and its web url to poll or continue. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | What to do, up to 4000 characters. | |
| label | No | Job title, up to 80 characters. Defaults to the goal's first line. | |
| model | No | Brain for this run: claude-opus-5-5, claude-opus-5, claude-sonnet-5, claude-fable-5-1, gpt-5.6-sol or gpt-6-astra. Absent means the account's default. A model test runs the same goal once per model. | |
| autoRun | No | Execute the plan the moment it is ready instead of pausing for approval. Deliverables still land as proposed drafts. | |
| timezone | No | IANA timezone for scheduling language in the goal. | |
| budgetUsd | No | Budget for the run, in dollars. | |
| mediaKeys | No | Media keys already in the account (from assets_upload or assets_list) to attach. | |
| characters | No | Actors to star in this job, by slug or id (characters_list). The agent always sees the whole roster; these are the ones it must use. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so safety is covered. Description adds meaningful context beyond annotations: server-side durability, returns job id and web url for polling, and the write-scope auth requirement. Doesn't cover rate limits or whether the run can be cancelled after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what it does, how it behaves, what it returns, what's required. Front-loaded and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, durability semantics, return shape (job id + url), and auth scope. No output schema exists, yet the description compensates by naming the return payload. Lacks guidance on when to use autoRun vs pausing, but that's 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. Description mentions files can be attached (mediaKeys) and the model field ('A model test runs the same goal once per model') but adds no more detail than the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Start a durable job from a goal'. Distinguishes from siblings like jobs_run and jobs_continue by describing server-side durability and the polling return. An agent can tell this creates a new job rather than resuming or listing 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?
Implied usage (creating a job when you have a goal), but no explicit when-to-use vs jobs_run, jobs_continue, or jobs_brief. The agent must infer selection from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One job in full: transcript, running/idle status, outputs (posts with queue state, media) and its web url. Use jobs_brief when you only need enough to reply. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing the required 'read scope' authorization and by describing the payload contents, which the annotations do not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with zero waste: the payload is front-loaded, then the sibling routing, then the auth requirement. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly compensates by enumerating return contents. For a single-record read tool it is nearly complete; only error/missing-job behavior is left unstated, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter with 100% schema description coverage ('The job id.'), so the schema already carries the parameter meaning. The description adds no format, id-source, or validity detail beyond that, making the baseline 3 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 ('One job in full') and enumerates exactly what is returned: transcript, running/idle status, outputs with queue state and media, and the web url. It explicitly distinguishes itself from the sibling jobs_brief, so an agent can choose 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?
Names the alternative tool (jobs_brief) together with the condition that selects it ('when you only need enough to reply'). The brief-vs-full routing decision is fully spelled out rather than left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List jobs with liveness and the web url of each, 200 per page, newest first. A non-null nextCursor means older jobs exist: pass it back as before. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| before | No | Cursor from the previous page's nextCursor. Omit for the newest page. | |
| origin | No | Filter by who started the thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe/read-only profile, so the bar is lower, and the description still adds real behavior: 200-item pages, newest-first ordering, the non-null nextCursor signal, and a required read scope. It stops short of richer detail like rate limits or whether filters affect pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, with the return shape and pagination rule front-loaded before the scope requirement. No filler or redundant clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully characterizes the return (liveness, web url, nextCursor) and the paging loop, which is the key missing structured data. It is nearly complete for a simple two-parameter list tool, lacking only filter interaction details for origin.
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 (before, origin) are already documented in the schema, and the description mostly restates the before/nextCursor relationship rather than adding syntax or format detail. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List jobs") and enumerates what each entry carries (liveness, web url), which lets an agent distinguish it from jobs_get at a glance. It does not explicitly name a sibling or contrast with jobs_tail/jobs_brief, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent can infer this is the enumeration entry point and that a "read scope" is required. There is no when-not guidance or explicit routing to alternatives such as jobs_get for a single job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press Run on the job's newest proposed plan - the approval click a headless caller has nobody to make. Use it after a turn ended with a plan waiting; deliverables still land as proposed drafts. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. | |
| budgetUsd | No | Budget for the run, in dollars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the annotations: it requires the write scope, selects the newest proposed plan implicitly, and discloses the outcome ('deliverables still land as proposed drafts'), which clarifies it is not a publish/destructive step and is consistent with destructiveHint=false. It does not address idempotency or what happens if no plan is pending.
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 action is front-loaded in the first clause and the three sentences each carry a distinct fact (what, when, side effect/permission). The parenthetical framing about a headless caller is stylistically long but does add rationale without derailing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema mutation tool, the description covers trigger, required scope, and post-run state (deliverables remain drafts), which is what an agent needs to call it safely. Missing only edge-case behavior such as running when no plan is waiting or with an invalid/expired job id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id, budgetUsd) are already documented in the schema; the baseline is 3. The description implies the id targets a job whose newest plan is run, but says nothing about the budgetUsd parameter or how it interacts with the run.
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 ('Press Run') on a specific resource ('the job's newest proposed plan'), so the agent knows exactly what action is taken and on which target. It does not name alternative siblings (e.g. jobs_continue, jobs_stop, posts_approve) to sharpen the boundary, keeping it 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 trigger condition: 'Use it after a turn ended with a plan waiting.' That is clear contextual guidance. It stops short of naming what to use instead when there is no pending plan (e.g. jobs_continue or jobs_get), so no explicit alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running job. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutating nature is known. The description adds genuinely new context by disclosing the required authorization ('Needs the write scope'), which is not derivable from the structured fields; it still omits whether the stop is reversible/idempotent and what happens to partial output.
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, zero filler, with the core action front-loaded and the permission prerequisite second. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation tool with no output schema and annotations that already carry the destructive/read-only profile, the description covers purpose and the auth requirement adequately. Minor gaps remain around reversibility and the state of a stopped job's artifacts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage, so the schema already documents 'id' fully. The description adds no format, sourcing, or validation detail beyond it, which is the expected baseline when the schema does the work.
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 (stop) and resource (job), and the qualifier 'running' scopes it to active jobs, which implicitly separates it from jobs_run and jobs_create. It stops short of an explicit sibling contrast, so it lands at clear-but-undifferentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the tool for halting an in-progress job. There is no statement of when not to use it, no mention of what happens if the job has already finished, and no reference to related siblings such as jobs_continue or jobs_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Watch a job's run: replays its events from the cursor, then follows live until the run ends, 60 seconds pass, or 200 events. Returns {live, cursor, events} - resume with that cursor. {live: false} means no run stream to attach to; the job may still have finished work, so read jobs_get. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. | |
| cursor | No | Resume from this cursor; omit to replay the run from its start. | |
| maxSeconds | No | How long to watch, 15 by default, 60 at most. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safe-read profile, but the description adds substantial behavioral context: replay-then-live semantics, the three termination conditions (run ends, 60 seconds, 200 events), the resume-token contract, and the auth scope needed. This is well beyond what the structured fields 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?
Three dense sentences, front-loaded with the operation and its streaming behavior, then the return shape, then the fallback and permission. No sentence is filler; each carries operational information the agent needs.
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, yet the description supplies the return shape ({live, cursor, events}), the termination rules, the resume path, and the authorization requirement. Nothing an agent needs to call and correctly interpret this tool 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, but the description adds meaning the schema lacks: it frames cursor as a resume token tied to the returned value ('resume with that cursor'), which clarifies the round-trip pattern. Minor note: it cites a 60-second live window while the schema defaults maxSeconds to 15, which slightly muddies the limit semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Watch a job's run') and immediately defines the mechanism: replay from cursor, then follow live. It also differentiates itself from the sibling jobs_get by naming it for the non-live case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear conditional route: when the result is {live: false} there is no stream to attach to and the agent should read jobs_get instead. It also states the read-scope requirement. It does not contrast with other plausible siblings like jobs_continue, jobs_brief, or jobs_run, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who this credential belongs to: email, plan, credit balance. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 value beyond that by disclosing the required auth scope and by listing the specific fields returned (email, plan, credit balance). It does not describe failure behavior when the scope is missing, which is a minor 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?
Two short clauses: what you get first, prerequisite second. Every clause carries information and nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly compensates by naming the returned fields (email, plan, credit balance) and the scope requirement. For a zero-parameter identity tool, 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?
The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify about inputs beyond the schema's empty object.
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 exactly what the tool returns — the identity behind the credential, enumerated as email, plan, and credit balance — so an agent knows the resource unambiguously. No sibling tool in the list overlaps with this identity/credential-read purpose, so differentiation is automatic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Needs the read scope" explicitly states the prerequisite for a successful call, which is real usage guidance. It doesn't state when-not-to-use, but no sibling overlaps, so there is no alternative to route away from.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every platform the rail posts to: text limit, media rules, whether documentTitle is required, first-comment support, and the JSON Schema for its settings. Read it before posts_create. Works with any key (read scope or none).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuine beyond-annotation context: the auth requirement ('read scope or none') and the fact that it returns per-platform constraints plus a settings schema, which tells the agent why this read matters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the resource and its payload, followed by the action directive. No filler or repetition of the 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?
With no output schema, the description compensates by naming the returned fields, so an agent knows what it will get. For a zero-param read tool whose annotations carry the safety profile, nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. Schema coverage is 100% on an empty object, so no gap remains.
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 (every platform the rail posts to) and enumerates exactly what it returns: text limit, media rules, documentTitle requirement, first-comment support, and the settings JSON Schema. This is far more specific than the title and clearly separable from siblings like agents_list or posts_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?
Explicitly instructs 'Read it before posts_create', naming the sibling tool whose call it should precede, and adds an auth-context note ('works with any key'). The when-to-use condition is stated rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PUBLISHES CONTENT: approving moves proposals to the schedule, and they will go out. Needs the publish scope.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Post ids to approve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real value: approving schedules content that 'will go out' (a consequential, hard-to-undo side effect) and requires the publish scope. It stops short of stating reversibility or bulk behavior across the ids array.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no padding: the consequence is front-loaded and the auth requirement follows. 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 mutation tool with annotations covering the safety profile and no output schema, the description supplies the key missing pieces (effect, auth scope). Only reversibility and post-approval state are left unstated.
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 with 100% schema description coverage ('Post ids to approve'), so the schema already carries the meaning. The description adds no format, limit, or selection guidance beyond that, making the baseline 3 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 the verb (approving) and the concrete effect (moves proposals to the schedule so they go out). The all-caps 'PUBLISHES CONTENT' opener is slightly ambiguous against the sibling posts_publish, but the scheduling detail differentiates it adequately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives one prerequisite ('Needs the publish scope') but does not say when to choose this over posts_publish or posts_dismiss, which are the obvious alternatives for acting on a post. Usage is implied rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PUBLISHES CONTENT: puts a post you wrote on the rail for one connected account (connections_list), at a time, in the account's next free queue slot, or now. Read platforms_list first for the platform's limits and settings schema. Free plan: 10 posts a day (402 free_daily_cap says when the day resets). Needs the publish scope.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The post text. | |
| queue | No | Instead of scheduledAt: the account's next free queue slot. | |
| title | No | The title; YouTube requires one. | |
| settings | No | Per-platform settings; the schema is platforms_list[].settingsSchema (TikTok privacyLevel, Reddit subreddit, YouTube privacyStatus). | |
| mediaKeys | No | Media already in the account (assets_upload returns keys). | |
| scheduledAt | No | ISO time it goes out. Omit for now. | |
| connectionId | Yes | The account to post as (connections_list). | |
| firstComment | No | Posted as the post's own first reply the moment it is live. LinkedIn (1250), X (280), Bluesky (300). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true and readOnly=false, and the description adds real operational context beyond them: the 10-posts/day free-plan cap, the 402 free_daily_cap reset signal, the required publish scope, and firstComment being posted the moment the post goes live. It does not explain why the action is flagged destructive (irreversibility/edits) which would complete the picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and a lead label, then moves through prerequisites and limits without much filler. The prose is dense and slightly clipped ("at a time, in the account's next free queue slot, or now") but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter mutation tool with a nested settings object and no output schema, it covers prerequisites, plan limits, scope, and media/key sourcing adequately. It omits what is returned (e.g. a post id for later posts_get/posts_approve) but nothing critical to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the queue/scheduledAt/now triad and cross-references connections_list, platforms_list and assets_upload, but largely restates what the schema already documents for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource up front ("PUBLISHES CONTENT: puts a post you wrote on the rail for one connected account") and clarifies scope (one account, one time, queue or now). It does not explicitly differentiate itself from the sibling posts_publish, which an agent could easily confuse with this create/publish action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete prerequisites ("Read platforms_list first for the platform's limits and settings schema", "Needs the publish scope") and clarifies the queue vs scheduledAt vs immediate choice. It stops short of naming when to prefer a sibling like posts_publish or posts_approve instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss proposed posts - nothing goes out. Needs the write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Post ids to dismiss. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds genuine value beyond annotations by stating the write scope is required for auth. However, annotations already declare destructiveHint=true, and the description never explains what 'dismissal' does to the posts (permanent removal? reversible? state change?), which is the key behavioral question for a destructive-flagged 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?
Two clipped sentences, zero filler, with the core action and the anti-publish clarification front-loaded. Nothing could be removed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool whose safety profile is covered by annotations and whose parameter is fully described by the schema, this is nearly sufficient. The one material gap is whether dismissed posts can be recovered, which matters given destructiveHint=true.
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 (ids) with 100% schema description coverage, so the schema already defines it fully. The description adds no format, batching, or limit guidance, leaving this 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 (dismiss) and resource (proposed posts), and the phrase 'nothing goes out' clearly separates it from the publish/approve siblings. It stops short of naming an alternative tool explicitly, so it is clear but not maximally differentiated.
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 implicit condition ('nothing goes out') scopes usage to non-publishing dismissal, but there is no explicit when-to-use vs when-to-use-posts_approve/posts_publish guidance and no stated prerequisites beyond the scope. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One post's live state. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The post id. |
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 a concrete auth requirement ('Needs the read scope') and hints at current/live data, but omits rate limits, error behavior, or return characteristics. With annotations carrying the safety profile, this added context is modest but real.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. The resource scope is front-loaded, followed by the auth prerequisite. Appropriately sized for a simple read-by-id 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?
The tool is simple and the schema/annotations cover the id and safety profile. However, with no output schema, the description does not explain what 'live state' returns or how missing posts are handled. It is minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single id parameter, so the schema fully documents it. The description adds no parameter-level semantics beyond implying the id identifies one post. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description, with the title 'Read a post', identifies the resource (one post) and its live state, distinguishing it from the list sibling posts_list by singling out a single post. It lacks an explicit verb in the description itself and does not name alternatives, but the scope is clear enough to invoke.
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?
No when-to-use guidance or alternatives are provided; the only context is the prerequisite 'Needs the read scope.' It does not say when to choose this over posts_list or other post tools, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The post queue: proposed drafts, scheduled posts, published history. Needs the read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Keep only posts in this state. |
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 non-annotation context by stating that read scope is required and by describing the 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?
The description is two short sentences, front-loads the resource scope, and then states the auth requirement. There is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional enum parameter and no output schema, the description covers what kind of queue is being listed and the required scope. It does not mention default status behavior or pagination, so it is not fully exhaustive, but it is adequate 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?
Schema coverage is 100%, so the status parameter and its enum values are fully documented in the schema. The description's mention of proposed, scheduled, and published posts gives partial semantic context, but the schema already carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as the post queue and enumerates the kinds of posts it contains, which makes the tool's scope clear. It does not explicitly contrast this tool with siblings such as posts_get or posts_create, so it stops 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?
It gives context that this lists the post queue and notes the required read scope, implying usage for browsing posts. However, it does not state when to use this tool versus alternatives like posts_get or when not to use it, leaving routing guidance mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PUBLISHES CONTENT NOW: pushes a queued post to the platform immediately. Needs the publish scope.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The post id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-structured fact — 'Needs the publish scope' — which is real authorization context. It stops short of saying whether publishing is reversible or what happens on failure.
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, zero filler. Every clause carries 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?
For a single-parameter mutation tool whose annotations already cover safety and openness, the description supplies the action, the precondition, and the required auth scope. Nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter, so the baseline is 3. The description hints the id refers to a queued post, but adds no format or constraint 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 with scope: 'pushes a queued post to the platform immediately.' The 'queued post' framing implies a lifecycle position relative to posts_approve/posts_create, but no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'queued' plus 'NOW' implies the precondition (an already-queued post) and the immediacy vs. scheduled publishing, but there is no explicit when-not guidance or routing to posts_approve/posts_create/postpone alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft, schedule and publish social media posts from any AI agent.
Schedule and publish to LinkedIn, X, and Threads from your AI. Content calendar, approval-first.
Post, schedule, and track social posts on X, Bluesky, LinkedIn, Instagram and more from AI agents.
AI-native social media publishing to LinkedIn, Instagram, Threads, TikTok, and X.
Add one secure layer between your agents and this server.
