Blog2Social - Social Media Publishing

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful context by disclosing the grouping dimension and the fallback default when days is omitted, but says nothing about auth scope, freshness, or limits beyond 30 days.

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

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

Two sentences, front-loaded with the return payload before the optional parameter detail. Slight redundancy in restating the 1-to-30 range that the schema already enforces, but the second half earns its place via the default behavior.

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?

An output schema exists, so return values need not be spelled out, and the description still summarizes them helpfully. For a zero-required-parameter read-only tool this is nearly complete; only the relationship to sibling tools is left unaddressed.

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

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

Schema coverage is 100% and the schema already documents the 1-30 range, so the baseline is 3. The description goes one step further by stating that omitting days falls back to an endpoint default, which the schema does not mention.

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 credit balance plus daily usage broken down by endpoint and network. An agent knows exactly what comes back, but the description never acknowledges the overlapping sibling credits.balance, so it doesn't fully differentiate itself.

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 only guidance is about the days parameter, not about when to choose this tool over credits.balance or networks.properties. There is no stated context, prerequisite, or exclusion, leaving the agent to infer that this is the account-wide rollup.

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 non-read-only, open-world, non-idempotent behavior, and the description adds real context beyond that: the response carries an auth_link the user must open, and Pinterest requires a pre-configured custom app assigned to the API service. It doesn't note that the connection stays pending until the user completes authorization, which is a minor omission.

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

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

Three sentences, front-loaded with the core action and followed by prerequisites and the return value. Every sentence carries information, though the Pinterest caveat is fairly dense relative to the rest.

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 an output schema exists, the description need not explain return values yet still flags auth_link, and it covers the prerequisite lookup and the Pinterest exception. The only gap is the post-authorization state (the connection is not yet live), which an agent might need for follow-up logic.

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

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

Schema description coverage is 100%, so all three parameters including the network_type_id mapping are already documented in the schema. The description repeats that mapping and adds the provenance of network_id, but no syntax or format details beyond the structured fields, 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 ('Starts authorization for a social network account'), which is clearly distinct from siblings connections.list and connections.remove. It also points to networks.list as the source of the required identifiers, so an agent can place it precisely in the workflow.

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

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

Gives clear context for use: pull network_id and account type from networks.list first, and it spells out the network_type_id mapping (0 profile, 1 page, 2 group). It stops short of stating when not to use it (e.g. when an account is already connected), so no explicit exclusions are offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the scope (accounts for the authenticated user) but no auth requirements, rate limits, or pagination context beyond what the annotations and output schema supply.

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

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

Two sentences with no filler: the first defines what is returned and what fields it carries, the second front-loads the actionable consumer instruction. Every sentence earns its place.

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

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

With an output schema present, the description need not explain return values, yet it helpfully summarizes the key fields. For a zero-param read-only listing tool this is nearly complete; only deeper operational context (e.g., whether the list can be empty or span multiple networks) is absent.

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, which is the baseline-4 case. The description additionally clarifies the meaning of a field in the response (client_user_network_id) and how to consume it, adding value beyond 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?

States a specific verb and resource ('Returns the social accounts currently connected to the authenticated Blog2Social user') and enumerates the returned fields, so it is clearly distinguishable from connections.add/remove and networks.list. It does not name a sibling alternative explicitly, but the read-only listing scope is unambiguous.

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

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

Gives concrete downstream guidance: use an account client_user_network_id in posts.create to choose the publish target, which tells an agent why it would call this tool. It lacks any explicit when-not or exclusion conditions, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is partially covered structurally. The description adds real context beyond them: the concrete consequence that the account can no longer be used for publishing unless reconnected.

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

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

Three tight sentences, front-loaded with the operation, then prerequisite, then consequence. 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?

An output schema exists, so return values need no explanation. Prerequisite sourcing, destructive consequence, and reversibility ('unless it is connected again') are all covered for a one-parameter mutation tool.

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

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

Schema coverage is 100% and the single parameter's schema description already states it is the ID returned by connections.list. The description's provenance note is therefore largely redundant, matching the baseline 3 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?

States a specific verb+resource ('Removes a social account connection') scoped to the authenticated Blog2Social user. It is immediately distinguishable from the sibling connections.add, which performs the inverse operation.

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

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

Explicitly instructs the agent to call connections.list first to obtain client_user_network_id, giving clear sequencing. It does not name an alternative tool for the same goal, but for a remove operation there is no meaningful sibling alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds meaningfully beyond them with the business rule that publishing is impossible at a zero balance, though it says nothing about auth requirements, rate limits, or caching of the 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 sentences, both earning their place: the first defines the return, the second defines when the agent should call it. The action-defining content is front-loaded.

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

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

An output schema exists, so return values need no explanation here. For a zero-parameter, read-only query the description supplies everything an agent needs: what it returns, the account scope, and the diagnostic condition that motivates calling 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 is nothing for the description to disambiguate and the baseline of 4 applies. The absence of any parameter discussion is not a gap here.

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 ("Returns") and resource ("the current credit balance of the authenticated Blog2Social API account"), with the account scope made explicit. No sibling tool (connections.*, networks.*, posts.create, videos.check) covers balance, so the agent can identify it immediately.

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

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

Gives an explicit trigger for invocation: check the balance "if a post cannot be published," which directly ties this tool to a failure scenario an agent will encounter. It doesn't name alternatives, but no sibling provides equivalent information, so no exclusion is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the shape of the result (which fields and support flags appear), which is content not behavior and largely duplicated by the output schema.

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

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

Two sentences, no filler: the first defines the result set, the second states how to use it. The most useful information (what you get) is front-loaded.

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

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

For a zero-parameter read tool with a full annotation profile and an output schema, nothing necessary is missing. The description supplies the workflow link to connections.add, which the structured fields cannot express.

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 identifiers mentioned (network_id, network_type_id) belong to the downstream connections.add call, not to this tool's own schema, so no parameter semantics need explaining here.

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 and resource ('Returns the social networks that can be connected to Blog2Social') and enumerates the returned fields (network name, URL, network_id, profile/page/group support). It also names the sibling it feeds into (connections.add), so an agent can distinguish it from connections.list and networks.list_properties.

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 the workflow: take network_id plus a supported network_type_id and pass them to connections.add. That is clear context and a named alternative, but there is no when-not guidance (e.g., when to use networks.list_properties instead of 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 readOnly, idempotent, non-destructive and open-world behavior, and an output schema exists, so the safety and return-shape burden is largely carried elsewhere. The description adds the useful note that the payload is static capability metadata, but nothing about freshness, caching, or coverage per network.

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

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

Two sentences, no filler: the first states what is returned, the second states when to consult it. The most decision-relevant information (the returned content) is front-loaded.

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

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

For a zero-parameter, read-only lookup with a full output schema and complete annotation coverage, the description supplies everything an agent needs: what it returns and the condition under which to call 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 no parameters, so the baseline is 4. There is no parameter syntax for the description to clarify, and it correctly avoids inventing any.

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 resource and enumerates concrete contents (media formats, video support, character limits) for a specific scope (network + account type). An agent can distinguish this from the sibling networks.list, though that distinction is implicit rather than stated.

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

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

"Check these requirements when preparing a post for a specific network and account type" gives a clear triggering condition that effectively routes the agent here before posts.create. No explicit exclusions or named alternatives, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description only needs to add context. It usefully discloses the async behavior difference — non-video posts return publish_url while video posts return a video_token to poll via videos.status — which is genuine behavioral detail. It omits any warning about duplicate/non-idempotent publishing, which matters given idempotentHint=false.

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

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

Purpose is front-loaded in the first sentence, followed by prerequisite, format mapping, and response handling in a logical order. It is a dense single paragraph with several chained clauses, but each clause carries distinct information.

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

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

Covers the prerequisite tool call, the format/media contract, and post-call handling for both sync and async outcomes, and an output schema exists so return shapes need not be spelled out further. Remaining gaps are around permissions and repeat-publish behavior for a non-idempotent, open-world write.

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 restates the postFormat mapping and the mediaObjects requirement for image/video posts, both of which are already documented in the schema's const and array descriptions, so it adds little beyond reinforcement.

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 ('Publishes a post') and pins the target to client_user_network_id, which cleanly separates it from the connections.* and videos.* siblings. An agent can identify the operation without opening the schema.

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

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

Gives real workflow guidance: check networks.properties for network-specific requirements before preparing the post, and pick postFormat 0/1/2 by content type. It never states when NOT to use it (e.g., drafts, scheduling, or re-posting), so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds real behavioral value by enumerating the three possible statuses per target account, explaining that publish_url appears only on success, and prescribing polling while pending. It stops short of describing timing/rate limits or the shape of the per-account result.

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

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

Three short sentences, front-loaded with the action, then return values, then the polling instruction. No filler and nothing repeated from the schema 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?

Given a single required param, full schema coverage, an output schema, and annotations covering the safety profile, the description supplies everything else an agent needs: the token's origin, the terminal and intermediate states, and the retry 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?

Only one parameter, and schema description coverage is 100% – the schema already documents video_token. The description mirrors that by noting it is the token returned by posts.create, adding provenance but no syntax or format detail 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 (checks) and resource (publishing status of a video post), and ties itself to the sibling posts.create by naming where the video_token originates. An agent can distinguish this polling/status tool from the creation tool 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 clear context on when to use it (after posts.create, with the returned video_token) and explicitly instructs to check again while status is pending. It does not state exclusions or what to do once all statuses are terminal, so it falls short of a full when/when-not statement.

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