Blog2Social - Social Media Publishing

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

Annotations declare non-readonly, open-world, non-idempotent behavior; the description adds real substance beyond that — the response contains an auth_link the user must open, and Pinterest lacks that link and instead needs a custom application (service_conditions_id). This is valuable flow-level disclosure for an external authorization 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?

Three tight sentences, front-loaded with the core action, then dependencies, then the exception. No filler and every sentence carries information.

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

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

With an output schema present and annotations covering the safety profile, the description does not need to explain return values; it still adds the crucial auth_link and Pinterest caveats. An agent has everything needed to invoke this correctly in-sequence after networks.list.

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

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

Schema coverage is 100%, so parameter meaning is already fully documented; the description largely repeats it (network_type_id meanings, network_id source). The only genuine addition is tying service_conditions_id to the Pinterest custom-application case, which is marginal beyond what the schema states.

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') and is clearly distinguishable from siblings like connections.list and connections.remove. The scope (an OAuth-style authorization flow) is unambiguous without opening the schema.

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

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

Gives clear context: obtain network_id and account type from networks.list before calling, and calls out the Pinterest exception with its special requirement. It does not explicitly say when NOT to use this versus connections.remove/list, but the flow condition is well implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, 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 openWorld, so the safety profile is covered. The description adds value beyond that by naming the categories of data returned, which is useful behavioral context for a reference-lookup tool.

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

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

Two tight sentences with the capability description front-loaded and the usage cue second. 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?

For a zero-parameter, read-only reference tool with an output schema already present and rich annotations, the description covers everything an agent needs: what it returns and when to call it. No return-value documentation is required.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies the lookup is keyed by network and account type at a higher level rather than via call arguments, and there is nothing further the schema needs to convey.

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

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

States a specific verb (Returns) and resource (publishing capabilities and limits per network and account type), with concrete examples of the data (media formats, video support, character limits). This clearly distinguishes it from siblings like networks.list (enumerates networks) and videos.check.

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

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

Explicitly says when to consult it: 'Check these requirements when preparing a post for a specific network and account type.' That ties it to posts.create, but it does not name alternative tools or state exclusions.

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

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

Annotations indicate a write operation (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds useful behavior beyond annotations: publish_url is returned for non-video posts, video posts return a video_token for videos.check. It doesn't mention failure modes, rate limits, or auth requirements.

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

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

Two sentences, front-loaded with the core action and followed by format-specific rules and response differences. No filler. Every clause earns its place.

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

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

Given a rich input schema and an output schema, the description covers the essential behavioral differences (media requirements, response tokens). It could mention that all posts in b2s_posts go to the same account or that the operation is not idempotent, but those are minor gaps.

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

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

Schema coverage is 100%, so the schema already documents parameters thoroughly. The description adds value by linking postFormat 0/1/2 to required companion fields (mediaObjects for 1 and 2) and explaining the response fields, which is semantic context beyond the schema text.

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

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

The description states a specific verb ('Publishes') and resource ('a post to the connected account') and identifies the exact target parameter client_user_network_id. This clearly distinguishes it from siblings like connections.list or videos.check.

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

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

The description explains postFormat values and when mediaObjects are required, and it names videos.check as the follow-up for video posts. It doesn't, however, state prerequisites like needing media uploaded first or limitations on which networks support which formats.

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 genuinely non-structured behavior: the pending/failed/successful outcome model and the instruction to re-poll while pending. It stops short of rate limits or timing guidance for the retry loop.

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

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

Three tight sentences with no filler; the tool's purpose, the token's origin, the possible outcomes, and the polling rule are all front-loaded in that order.

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

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

For a one-parameter read tool with an output schema and full annotations, nothing an agent needs is missing: the source of the token, the returned status values, the success-only publish_url, and the re-poll condition while pending are all stated.

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

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

Schema coverage is 100% with a single, well-described parameter, so the baseline is 3. The description adds only the provenance of video_token (returned by posts.create), which is useful context but not new syntax or format detail.

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

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

States a specific verb and resource ('Checks the publishing status of a video post') and ties the input to its producer ('using the video_token returned by posts.create'), cleanly separating it from the sibling write tool posts.create. An agent can identify the tool's job without opening the schema.

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

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

Gives the operative usage rule for a polling tool: 'check again while the status is pending', which tells the agent when to re-invoke. It also anchors the call to the posts.create workflow, though it names no explicit alternative or when-not condition.

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