Postproxy

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds context by detailing what it checks (auth, API config, workspace info). There is no contradiction with annotations, and the description provides behavioral insight beyond 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?

The description is a single, front-loaded sentence that conveys all necessary information without any filler or redundancy. Every word 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 the tool's simplicity (0 parameters, read-only, no output schema), the description completely covers what the tool does. It specifies exactly what information is checked (auth, API config, workspace info), leaving no 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?

The input schema has zero parameters, and schema description coverage is 100%. The description does not need to add parameter info. Baseline is 3, but given the simplicity, the description is sufficient and clear.

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 clearly states 'Check authentication status, API configuration, and workspace information', specifying the verb 'Check' and distinct resources. This differentiates it from sibling tools that handle comments, posts, DMs, etc., with no tautology.

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 implies usage for verifying auth or workspace info, but provides no explicit guidance on when to use this tool versus alternatives or exclusions. It could be improved by stating that it is a safe, read-only operation for initial setup or troubleshooting.

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 it is a non-read-only, non-idempotent, destructive, open-world operation; the description adds one genuinely useful behavioral fact — publishing to the platform happens asynchronously. It omits other behavioral context an agent needs, such as whether retries create duplicate comments and what permissions/profiles are required.

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 zero waste: the core action is front-loaded and the platform-scope sentence is short and informative. Nothing is 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?

With no output schema, the description should say what the call returns and how to learn the outcome of the async publish (e.g., a status check), which it does not. The async disclosure helps but leaves the agent unsure how to confirm the comment actually landed.

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

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

Schema description coverage is 100%, so post_id, profile_id, text, and parent_id (including reply-vs-top-level semantics) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline 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+resource ("Create a comment or reply on a published post") and constrains scope to published posts, which separates it from comments_edit/comments_delete/comments_get. It does not distinguish itself from the ambiguous sibling profile_comments_create, so no explicit sibling differentiation.

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

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

Implies usage (creating a comment or a reply, with platform support listed for Instagram, Facebook, Threads, YouTube, LinkedIn), but never states when-not to use it or points to an alternative such as profile_comments_create or dm_comment_private_reply.

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?

Description adds value beyond annotations by stating the operation is asynchronous and listing supported platforms. No contradiction with annotations (destructiveHint=true, idempotentHint=true).

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 concise sentences that cover purpose, async nature, and platform support. No unnecessary 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?

Covers essential aspects: purpose, async, platforms. Lacks mention of error conditions or what happens upon success, but for a delete tool with no output schema, this is adequate.

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?

All three parameters are fully described in the input schema (100% coverage). Description does not add additional meaning beyond what the schema provides, so baseline score 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?

Clear verb 'delete' with specific resource 'comment' and list of platforms. Distinguishes from siblings like comments_hide and comments_unlike by explicitly stating deletion.

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?

Mentions asynchronous execution and platform support (Instagram, Facebook, YouTube, LinkedIn) but does not explicitly state when to use this tool versus alternatives like hiding or unliking a comment.

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

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

Adds substantial behavior beyond the annotations: the operation is asynchronous, it returns only { accepted: true }, and completion arrives via the comment.edited / comment.edit_failed webhooks. The annotations only declare it non-read-only and idempotent; the async contract and webhook names are exactly the context an agent cannot get elsewhere.

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 action and the async/webhook consequence are front-loaded in order of importance.

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

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

No output schema exists, yet the description explains the return shape and how the real result is delivered, plus the platform restriction. For a 4-param async mutation this covers everything an agent needs to call and interpret it.

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

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

Schema description coverage is 100%, so post_id, comment_id, profile_id and body are already documented in the schema. The description adds no format, ID-type, or body-length nuance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Edit the text of a comment') plus an ownership scope ('you published'), which cleanly separates it from comments_create, comments_delete, comments_hide, and comments_like among the siblings. An agent can route to it 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 a real usage constraint — 'Supported on Facebook and YouTube only' — which prevents calling it on unsupported platforms. It stops short of naming alternatives (e.g. comments_delete for removal), so it is clear context rather than full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, and description adds return of replies, but does not disclose structure or limitations.

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?

Single short sentence, to the point with no unnecessary 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?

Adequate for a simple read operation with 3 parameters; could mention response format or field details but not necessary.

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 descriptions for all parameters; the description adds no new parameter information.

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 clearly states the action ('Get') and the resource ('a single comment with its replies'), distinguishing it from siblings like comments_list which would list comments.

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 explicit guidance on when to use this tool versus alternatives like comments_list or profile_comments_get; context is implied but not stated.

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

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

The description adds value beyond annotations by noting the operation is asynchronous and listing supported platforms. Annotations already indicate destructive and idempotent behavior; the description reinforces these traits without contradiction.

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 extremely concise—only two short sentences—covering the key points without any extraneous information. It is front-loaded with the action and platforms.

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 description is adequate for a simple tool with three required parameters and full schema coverage. However, it lacks details about success/failure responses, reversibility (though implied by 'comments_unhide'), and implications of asynchronous execution.

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 does not add additional context beyond the schema's parameter descriptions (e.g., 'Post ID', 'Comment ID (Postproxy ID or external ID)'), so no extra credit.

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 clearly states the action ('Hide a comment') and specifies the platforms (Instagram, Facebook, and Threads). It distinguishes from sibling tools like 'comments_delete' and 'comments_unhide' by using the verb 'hide'.

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 guidance is provided on when to use this tool versus alternatives like 'comments_delete' or 'comments_unhide'. The description mentions 'asynchronously' but does not elaborate on expected behavior or when hiding is preferred over deleting.

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 indicate idempotentHint=true and non-destructive, but the description adds valuable context: the operation is asynchronous and currently limited to Facebook. No contradictions.

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 wasted words. Front-loaded with the action and resource, then clarifies async and platform support.

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 tool with no output schema and fully described parameters, the description is complete. It covers the key behavioral aspects (async, platform) and is self-sufficient.

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 descriptions for all three parameters. The description does not add additional meaning beyond what the schema provides, so baseline score of 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 clearly states the action (like) and resource (comment), and distinguishes from siblings like comments_unlike. It also notes the async nature and Facebook-only limitation.

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 specifies when to use (for liking comments) and implies limitations (only Facebook), but does not explicitly mention when not to use or provide alternatives.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world). The description adds genuinely useful behavior beyond them: the return shape (paginated top-level comments with nested replies) and the platform-support limitation that may cause empty/unsupported results.

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

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

Four sentences, each carrying content, with the core action front-loaded. No filler or redundancy, though it is slightly prose-y rather than maximally tight.

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 describing the return structure, and annotations cover safety while the schema covers all parameters. The platform-support caveat closes the last gap; only explicit pagination/return-volume guidance 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?

Schema description coverage is 100%, so all six parameters are already documented in detail, including that from/to filter on PostProxy receipt time. The description's restatement ('filter by when PostProxy received the comment with from/to') adds only marginal value over the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List comments on a published post') and adds scope detail (paginated top-level comments with nested replies). It is clearly distinguishable from write siblings like comments_create/comments_delete, though it never explicitly names an alternative tool, 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?

The description implies the use context (reading comments on a post) and offers a useful caveat ('Not all platforms support comments'), but it gives no explicit when-to-use vs alternatives guidance and does not route the agent to siblings such as comments_get or profile_comments_list.

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 mark it as non-readOnly, non-destructive, and idempotent. The description adds the 'asynchronously' behavior and platform support (Instagram, Facebook, Threads), providing useful context beyond annotations.

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 sentence that is front-loaded with the action and includes only essential information (platforms). 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 simple unhide operation with 3 required parameters, no output schema, and comprehensive annotations, the description is complete and sufficient. It mentions key platforms and the asynchronous nature.

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 parameter descriptions are present but minimal. The tool description does not add any extra meaning or format details beyond the schema, so it meets the baseline.

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

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

The description clearly states the action (unhide) and the resource (a previously hidden comment), distinguishing it from siblings like comments_hide or comments_delete.

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 implies the tool should be used after hiding a comment, but does not explicitly state when to use vs alternatives or exclude cases where comment is already unhidden (though idempotentHint covers this).

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

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

Adds context beyond annotations: async execution and Facebook-only support. Annotations already indicate idempotent and non-destructive. No contradictions.

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?

Single sentence with no extraneous information. Very concise and front-loaded with key 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 purpose and constraints (Facebook, async). Missing explicit mention of return value, but as an async operation, it is acceptable. Adequate given the simplicity of the action.

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 descriptions for all three parameters. The tool description adds no additional parameter-specific information beyond what the schema already provides.

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

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

The description clearly states the action ('Remove a like from a comment'), the resource (comment), the platform (Facebook), and the async nature. Differentiates from siblings like comments_like.

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?

Specifies that it is currently only supported on Facebook, giving a clear context for use. Does not explicitly list alternatives, but the sibling list includes comments_like, implying when to use the opposite.

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 idempotentHint=true and destructiveHint=false. The description adds specific behavioral details: it calls Bluesky's muteConvo and returns the chat with archived:true. This adds value beyond annotations.

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 extremely concise: two sentences with no wasted words. The primary action is front-loaded ('Archive (mute) a chat'), followed by platform and behavior details.

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 toggle operation with one parameter and no output schema, the description sufficiently covers the behavior. It could optionally mention the reversible nature via sibling, but not required.

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

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

Schema coverage is 100% and the description does not add any parameter-specific information beyond what the schema provides (chat_id is described as 'Chat hashid OR external_conversation_id' in both). Baseline of 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 clearly states the action ('Archive (mute) a chat'), the platform ('Bluesky only'), and the API call ('calls Bluesky's muteConvo'). It distinguishes from the sibling 'dm_chat_unarchive' by stating the operation and return value.

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 platform context ('Bluesky only') which helps when to use. It does not explicitly state when not to use or mention alternative tools, but the sibling 'dm_chat_unarchive' implies the opposite operation.

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 idempotentHint, readOnlyHint=false, destructiveHint=false, and openWorldHint, so safety is covered. The description adds real behavioral context beyond them: WhatsApp requires placement_id and a template-opened conversation, and the call returns the existing chat rather than erroring. That is meaningful added disclosure.

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

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

Two sentences, front-loaded with the find-or-create purpose before usage and platform caveats. It is somewhat dense and packs multiple platform rules into the second sentence, but every clause carries actionable information.

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

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

For a mutation tool with no output schema, the description covers return behavior (returns existing chat if present), the pre-send usage flow, and WhatsApp prerequisites. Missing only an explicit pointer to the sibling read tool, which would make it fully self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an upgrade by adding platform-conditional meaning: placement_id is required on WhatsApp (phone number id from profiles_placements) and participant_external_id must be digits-only international format there. It adds format and conditional-requirement context the schema alone doesn't fully 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+resource ('Find or create a chat') and scopes it ('for a participant on a DM-capable profile'), which separates it from siblings like dm_chat_get or dm_chats_list without opening a schema. The idempotent qualifier sharpens the contract.

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 gives the triggering situation: 'Use before sending a message to a participant the profile has not yet messaged,' and routes WhatsApp users to dm_message_send for required templates. It does not name the read alternative (dm_chat_get) or state when not to use it, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only, safe behavior is clear. The description adds the identification detail but does not contradict annotations. It contributes minimal additional behavioral context.

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

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

The description is a single, clear sentence with no extraneous words. All information is front-loaded and efficient.

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 read-only retrieval tool with comprehensive annotations, the description sufficiently covers how to identify the chat. It lacks explicit mention of response contents, but this is implied by 'Get a single chat'. No output schema exists, but the tool's simplicity reduces the need for extra details.

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% for the single parameter. The description repeats the allowable values (hashid or external_conversation_id) already documented in the schema, adding no new semantic 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 clearly states the tool retrieves a single chat using either a Postproxy hashid or an external_conversation_id, precisely identifying the resource and identification method. It distinguishes from siblings like dm_chats_list (list) and dm_chat_create (create).

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 specifies the two identification methods but provides no guidance on when to use this tool versus alternatives such as dm_chats_list. No exclusions or when-not-to-use information is given.

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

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

Annotations only declare it is a non-destructive, idempotent, open-world mutation; the description adds the crucial externally visible consequence that on WhatsApp this fires a read receipt (blue ticks) to the participant while on other networks it only writes local metadata.read_at, and notes the return value. That is real behavioral context beyond 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?

Three tight sentences, front-loaded with the action, then the platform-specific behavior, then the return value. No filler and 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 a single-parameter mutation with full schema coverage and annotations covering the safety profile, the description covers action, side effects, and return value. Only the absence of any precondition/routing guidance keeps it short of fully 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% and chat_id already documents that it accepts a hashid or external_conversation_id, so the description adds no parameter-level meaning. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource ('Mark a chat as read') and immediately scopes the effect by platform, so an agent can tell exactly what operation this is and how it differs in behavior from any other dm_* tool.

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

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

Usage is implied by the operation itself, but the description never states when to prefer this over adjacent tools (e.g. dm_chat_archive) or any precondition for calling it. Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds genuine behavior: ordering by most recent activity and the WhatsApp-specific return fields (external_placement_id, group, within_messaging_window), which tell the agent to expect schema variance per platform.

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 ordering, then platform scope, then the WhatsApp field caveat. Dense but every clause carries information; the platform enumeration is slightly list-heavy but earns its place.

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

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

With no output schema and only annotation-level safety info, the description does meaningful work by flagging WhatsApp-only return fields and the recency ordering. It stops short of describing the general chat object shape or pagination interaction for non-WhatsApp platforms.

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 page, after, before, per_page and profile_id are already documented with types and semantics. The description adds no parameter-level detail (e.g., how after/before interact with ordering), 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?

Names a specific verb and resource ('List direct-message chats (conversations)') and adds scope ('for a DM-capable profile'), which clearly separates it from dm_messages_list and dm_chat_get. It does not explicitly name those siblings, but the resource noun alone makes the distinction legible.

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 (enumerate a profile's chats, most recent first) and the supported-platform list gives useful context, but there is no explicit when-to-use rule, no exclusions, and no routing to dm_messages_list for message-level data or dm_chat_get for a single chat.

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 idempotentHint=true and destructiveHint=false, and the description adds that it calls Bluesky's unmuteConvo and returns a chat with archived: false. This provides sufficient transparency beyond annotations, though no side effects or prerequisites are mentioned.

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 concise sentences, front-loading the primary action and adding necessary context about the return value. 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?

Given the single parameter, full schema coverage, no output schema, and adequate annotations, the description fully explains the tool's purpose, behavior, and return value without 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% with a clear description for chat_id. The tool description does not add meaning beyond what the schema already provides, which is acceptable but not exceptional.

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 clearly states it unarchives/unmutes a chat, specifies the platform (Bluesky only), calls Bluesky's unmuteConvo, and returns the chat with archived: false. This distinguishes it from sibling tools like dm_chat_archive and dm_chat_get.

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?

While the description doesn't explicitly state when to use it vs alternatives, it is clearly the inverse of dm_chat_archive, and the sibling list provides enough context. A slightly higher score would require explicit direction.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds rich context beyond them: it auto-creates/reuses a chat, is hard-limited to one reply per comment ever, bypasses the 24h window, and omits media attachments. These are exactly the operational traits an agent needs before calling a write tool.

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

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

Front-loads purpose in the first clause, then layers constraints and interactive-element behavior. It is dense but nearly every clause carries a distinct, decision-relevant fact; only the dm_message_send parity sentence is arguably 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 mutation tool with no output schema and seven parameters, the description covers the platform scope, the one-shot constraint, window bypass, and how postback taps surface as inbound messages. An agent has everything needed to call it correctly and anticipate the side effects.

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 cross-parameter constraints not encoded in the schema: text is capped at 80 characters when buttons are present, media is unavailable, and quick replies cannot be combined with buttons on Instagram. This meaningfully extends what the schema alone conveys.

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 precise verb+resource ('Send a DM to the author of a comment, in reply to that comment') and names the Meta concept ('Private Replies'). The scope ('Instagram and Facebook (Page comments) only') and the implicit contrast with dm_message_send, which it references for interactive-element parity, let an agent place it correctly among siblings.

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

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

Gives strong usage context: bypasses the 24h window for comments up to 7 days old, one private reply per comment ever, and platform limits. It references dm_message_send but only for feature parity, not as an explicit 'use that instead when X' routing rule, so it stops just short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the Telegram-only limitation, and that passing {} to reply_markup clears an existing keyboard. It does not mention auth requirements, rate limits, or edit-window constraints, so it is strong but not exhaustive.

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 action and its platform scope, followed by the constraint. Every sentence carries information, though the Meta quick_replies/buttons clause is somewhat redundant with the preceding 'Facebook and Instagram do not expose outbound edits'.

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

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

No output schema exists, and this is a destructive mutation on an open-world platform, yet the description covers platform scope, parameter constraints, and keyboard-clearing behavior adequately. It omits failure modes and edit-window limits, which would be useful for a destructive edit but are not strictly required to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes a cross-parameter constraint the schema cannot express: 'at least one of body/reply_markup is required' even though only message_id is schema-required. It also reinforces the {} semantics for reply_markup.

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 (edit) and resource (a previously-sent outbound message) with the scope narrowed to Telegram. An agent can distinguish it from dm_message_send (new message), dm_message_react, and comments_edit without opening any schema.

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

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

Explicitly states when the tool is unavailable (Facebook/Instagram do not expose outbound edits, so Meta quick_replies/buttons cannot be changed) and gives the precondition that at least one of body/reply_markup is required. It does not, however, name a sibling alternative for the unsupported platforms, so routing guidance is one step short of complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further, disclosing return-shape behavior that annotations cannot: outbound messages echo quick_replies/buttons/card, and inbound tap messages carry tapped_action with kind/payload/title — genuinely useful context since no output schema exists.

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

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

Two sentences, zero filler, with the core action front-loaded ahead of the supporting return-value detail. Efficient and easy to scan.

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

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

With no output schema, the description steps in to describe notable return content, which is the right call for a single-item getter. It omits error behavior (e.g., unknown identifier) but is otherwise sufficient 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 description coverage is 100% and the message_id field already documents 'Message hashid OR external_id'. The description restates this, only marginally sharpening it with the 'Postproxy hashid' qualifier, so it adds little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get a single message') and enumerates the two accepted identifiers (Postproxy hashid or external_id). The 'single message' scope implicitly separates it from dm_messages_list, though it never names a sibling explicitly.

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

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

Usage is implied rather than stated: the agent infers it should call this when it already holds a message identifier. There is no guidance on when to prefer dm_messages_list versus this tool, and no mention of prerequisites or paging context.

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 idempotentHint=true and destructiveHint=false, and the description explains the replace-on-second-react semantics that back the idempotency claim, plus platform availability. It doesn't address auth/permission requirements beyond 'your business account', but adds genuine context over 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?

Three tight sentences, front-loaded with the action, then platform scope, then per-platform parameter rule, then the replace behavior. No filler; 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?

For a mutation tool with full annotations and no output schema, the description covers platform scope, parameter rules, and the idempotent replace behavior. Remaining gaps (success/return shape, error cases) are minor against the annotation coverage.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter behavior the schema doesn't: WhatsApp ignores 'reaction' and requires 'emoji', and a second react replaces the prior one. That is meaningful semantic value beyond the per-field descriptions.

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 ('Add a reaction from your business account to a message') and scopes it to three named platforms with explicit exclusions (not Telegram or Bluesky). Together with the sibling dm_message_unreact, the write direction 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 platform-conditional guidance: on WhatsApp pass emoji and ignore reaction names, while Instagram/Messenger use named reactions. It does not explicitly route the agent to dm_message_unreact or state prerequisites, but the platform context is clear enough to invoke correctly.

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

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

Annotations declare the mutation/safety profile, and the description adds substantial context beyond them: asynchronous queueing with status: pending, the 422 on free-form sends outside the 24h window, tag extending the window to 7 days, and the suspension risk from misuse. This is exactly the operational context an agent needs before calling a destructive send.

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

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

Front-loaded with the core action and the exclusivity rule, and every sentence carries real information for a 17-param multi-platform tool. It reads as a dense wall of text in one paragraph, which slightly hurts scannability, but 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?

Covers async delivery, platform support boundaries, window/permission rules, and even return-state behavior (status: pending, status: failed with error_details) despite having no output schema. For a tool this complex, the description is complete enough to call correctly.

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

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

Schema coverage is 100% and the schema already labels each param's platform, so baseline is 3. The description adds genuine cross-parameter value the schema lacks: the one-of exclusivity between body/media/template/interactive/location/contacts, the WhatsApp window mechanics, and the note that quick_replies/buttons/card are rejected outside Facebook/Instagram.

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 ('Send an outbound direct message') with clear scope (outbound, asynchronous). The platform-specific detail makes it unmistakable versus siblings like dm_message_edit or dm_message_react.

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

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

Explicit exclusivity rule ('Provide EXACTLY ONE of body, media, or — on WhatsApp — template, interactive, location or contacts') plus when-to-use guidance for templates, tag:HUMAN_AGENT, and category:utility. States when-not (never for promotional/automated content) and names the alternative route for re-opening the window.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: deterministic ordering (most recent first) and, importantly, that tapped interactive-element messages expose tapped_action {kind, payload, title} so the agent should read the payload there rather than parse platform_data. That is a non-obvious behavioral detail an agent would otherwise miss.

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 purpose and ordering before the filter detail. The second sentence is dense with a long parenthetical enumeration of interactive element types, but each clause carries actionable information rather than 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?

There is no output schema, so the description carries some return-shape burden and does address it by explaining the tapped_action structure. With 100% parameter coverage and annotation-declared safety, the only mild omission is pagination behavior, which is largely covered by the schema's page/per_page descriptions.

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

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

Schema description coverage is 100%, so all five parameters (page, status, chat_id, per_page, direction) are already documented in the schema; the description only echoes direction and status. Baseline 3 applies. The tapped_action detail is about return data, not parameters, so it does not raise this dimension.

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 messages in a chat") plus a result ordering ("most recent first"), which implicitly separates it from the singular dm_message_get and the write-oriented dm_message_send. It stops short of explicitly naming an alternative sibling, so it lands at 4 rather than 5.

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

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

It says filters are optional and which two dimensions can be filtered (direction, status), which is implied usage guidance. But there is no explicit when-to-use-this vs dm_message_get or dm_chats_list, and no stated prerequisites for the chat_id. Adequate but with a clear gap.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful nuance by narrowing scope to 'your business account's reaction' only, but says nothing about permissions, whether the reaction must already exist, or failure behavior.

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

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

Two short front-loaded sentences: the action first, the platform constraint second. No wasted text.

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, idempotent, non-destructive tool with full schema coverage and annotations, the description is nearly sufficient. It covers action and platform scope but omits any error-case or precondition context, keeping it just short of 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?

With one parameter and 100% schema description coverage, the schema already explains that message_id accepts a hashid or external_id. The description adds no additional meaning about the identifier format. 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 ('Remove') and resource ('your business account's reaction from a message'), which cleanly distinguishes it from the sibling dm_message_react. An agent can tell the two apart 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?

The description names the applicable platforms (Messenger, Instagram Direct, WhatsApp), which is useful scoping, but never states when to prefer this over dm_message_react or any error/precondition for unreacting. Usage is only 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=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context that valid attributes depend on primary category and region and describes the two modes, but it gives no detail on pagination behavior or result shape despite having no output schema.

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

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

Two dense, front-loaded sentences with no filler. The critical dependency (call before update) is stated immediately and the mode rules follow compactly.

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

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

For a read-only listing tool with no output schema, the description covers purpose, ordering dependency, and mode selection well. It could say more about the returned value-type metadata or paging, but 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that region_code/language_code should be omitted in the default location mode and that region_code is required in category_name mode, clarifying the interdependency beyond the schema's per-field notes.

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

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

States a specific verb (List) and resource (attributes a location can set) plus the returned detail (value types). It clearly distinguishes itself from google_business_attributes_get and google_business_attributes_update by describing discovery of settable attributes rather than reading or writing them.

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

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

Explicitly says to ALWAYS call this before google_business_attributes_update, and names the sibling alternative. It also lays out the two invocation modes (by location as default, or by category_name) with the condition selecting each.

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=true, destructiveHint=false, openWorldHint=false), so the description is not obligated to restate safety. It does add genuinely useful behavioral context: Google omits the `attributes` key entirely when none are set instead of returning an empty array, which is exactly the kind of edge case an agent would otherwise mishandle.

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 core action and its scope lead, and the non-obvious empty-response quirk follows as a targeted caveat.

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 annotations covering safety and a fully documented two-param schema, the remaining gap was return-shape behavior, which the description addresses via the omitted-`attributes`-key note. No output schema exists, so this is close to sufficient; explicit sibling routing is the only real omission.

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

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

Schema description coverage is 100%, with both profile_id and location_id documented (including the 'accounts/X/locations/Y' format). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('attributes currently set on a Google Business Profile location') and enumerates example attribute groups (payments, accessibility, service options, social links). The phrase 'currently set' implicitly separates it from google_business_attributes_available, but the sibling is never named, so the differentiation 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?

No explicit when-to-use or when-not-to-use guidance and no named alternative. The words 'currently set' imply this is the read-side counterpart to google_business_attributes_update, but the agent must infer that routing itself.

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

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

Annotations already declare destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description adds non-obvious behavioral detail: attribute_mask defaults to exactly the names sent, so untouched attributes are preserved, and deliberately widened masks remove attributes absent from the payload.

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 tightly packed sentences with zero filler. The core action leads, the value-shape rules follow, and the mask-default caveat closes it out.

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

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

For a mutation tool with no output schema, it covers the required inputs, the payload shape, and the destructive edge case. It does not describe the response body or error behaviour, though annotations already carry the safety profile.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description goes well beyond it by spelling out the concrete value shape per valueType (BOOL values: [true], URL uriValues, ENUM repeatedEnumValue). That resolves the ambiguity of an untyped array of objects.

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: 'Set attributes on a Google Business Profile location.' It also names the related tool google_business_attributes_available, signalling that this tool writes values whose shape that sibling defines, which cleanly separates it from the get/available siblings.

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

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

It tells the agent to consult google_business_attributes_available for the valueType before constructing a value, giving a clear precondition. It stops short of explicit when-not-to-use or alternative guidance (e.g. vs google_business_attributes_get).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the category set is region-dependent, results are numerous (thousands), and the values returned are resource names rather than display names.

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 purpose and output shape, followed by the why (patches need resource names) and the practical filtering tip. 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 read-only lookup with full schema coverage and no output schema, the description covers purpose, output value form, and the key scale/region caveats. It does not describe pagination flow or default view behavior, but those are already in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including filter syntax, page_size clamping, and the view enum. The description reinforces filter's purpose but adds no syntax or format detail the schema lacks; 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 a specific verb and resource ('Resolve Google business category resource names ... for a region') and even shows the output format ('categories/gcid:software_company'). It is the only category-listing tool among the google_business_* siblings, so an agent can place 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?

It gives a clear operational condition: use `filter` to search by display name instead of paging through thousands of results, and it explains the resource-name-vs-display-name distinction needed for category patches. It stops short of explicit when-not-to-use or named alternatives, but there is no obvious sibling competitor.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond annotations by warning that a 422 FAILED_PRECONDITION is expected for non-restaurant locations and should not be retried — a non-obvious behavior an agent would otherwise mishandle.

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 the important error-semantics caveat. No filler or repetition of schema/annotation content.

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

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

For a read-only tool with full schema coverage and no output schema, the description covers purpose and the key error behavior. It does not sketch what a returned menu looks like, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, with all three parameters documented in the schema (including the 'fields' read mask). The description adds no parameter-level syntax or format detail, 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 ('Read') and resource ('food menus') scoped to a Google Business Profile location. It is immediately distinguishable from the sibling google_business_food_menus_update, which differs only by verb.

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 applicability condition: 'Restaurant-like categories only', and explains the failure mode for other locations (422 FAILED_PRECONDITION). It does not name the update sibling as an alternative, but the when-to-use context is clear and actionable.

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, but the description makes the destruction concrete ('full replacement, not a merge') and adds a concrete error contract (422 when canHaveFoodMenus is absent). It does not cover auth/permission requirements or rate limits, so it is strong but not exhaustive.

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

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

Four dense sentences, each earning its place: replacement semantics first, then structure, then the prerequisite/error condition. No filler and the critical constraint 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 3-parameter mutation tool with full annotation coverage and no output schema, the description covers the destructive semantics, the nested data shape, and the failure mode. Nothing essential for calling 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, but the description adds meaning by explaining the menu -> sections -> items nesting and the required languageCode/currencyCode/units fields that the agent must populate inside the free-form menus array. This is genuinely useful beyond the schema's terse example.

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 (replace) and resource (food menus on a Google Business Profile location), and the word 'Replace' plus 'Full replacement, not a merge' immediately distinguishes it from the sibling google_business_food_menus_get. An agent can tell what it does 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 and a real precondition: the location must have metadata.canHaveFoodMenus or the call returns 422, and the operation is a full replacement rather than a merge. However, it never explicitly names google_business_food_menus_get as the read alternative or spells out when to prefer one over the other, so routing is left partly to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the crucial replace semantics ('each block you name in `fields` is replaced entirely'), which tells the agent exactly what gets destroyed and complements the destructive hint with real scope detail.

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 tightly packed sentences, front-loaded with the operation, then format, then the read-and-replace semantics. No filler; 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?

For a destructive mutation with nested objects and no output schema, the description covers the replacement semantics and time format well. It omits auth/permission requirements and does not explicitly confirm that unnamed blocks are left untouched, minor gaps given the rich schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds format guidance the schema lacks: accepted time strings like '09:00'/'09:00:00' versus Google's { hours, minutes } objects. That is meaningful input-format information beyond the structured fields.

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 (Set) and resource (opening hours on a Google Business Profile location), which cleanly distinguishes it from the sibling read tool google_business_location_get and the unrelated google_business_location_update. 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?

Explicitly routes the agent to google_business_location_get to read current hours before writing, establishing the workflow. It stops short of stating when NOT to use this tool or explicitly warning that partial updates require sending the full block, so it is strong context rather than complete guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond the annotations: the field-masked update workflow and the requirement to fetch before updating. It doesn't mention auth or rate limits, keeping it just short of 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 tight sentences, front-loaded with what is read, then the disambiguation from posts, then the update-workflow prerequisite. Every sentence carries distinct, non-redundant value.

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 compensates by enumerating the returned fields, and it covers the read-before-update workflow that an agent needs. 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%, so profile_id, location_id, and read_mask are already fully documented in the schema. The description does not elaborate on parameter syntax or formats (e.g., the read_mask field-path convention), so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('Google Business Profile location'), then enumerates the fields returned (name, description, website, phones, categories, address, hours, etc.). It explicitly distinguishes itself from the posts resource ('This is the business listing itself, not posts published to it'), separating it from sibling post_* tools.

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

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

Gives explicit when-to-use guidance: 'Read this before any google_business_*_update,' and explains why (Google's updates are field-masked, so you patch back objects fetched here). This is a concrete prerequisite workflow that routes the agent correctly relative to the *_update siblings.

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, yet the description adds the specific destructive mechanism an agent actually needs: fields named but absent from the payload are CLEARED and nested objects are replaced wholesale rather than merged. That is exactly the kind of non-obvious write semantics annotations cannot express.

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

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

Three sentences, zero filler, and the highest-risk information (the clear-and-replace semantics of `fields`) is front-loaded right after the purpose statement. The prerequisite read and the sibling exclusions are compressed into single 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?

For a 14-parameter mutation with no output schema and an openWorld profile, the description covers the destructive mechanics, the read-first workflow, and sibling boundaries well. It stops short of describing what the response returns or the permission/auth requirements for the update, which would complete the picture.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning to the `fields` parameter by defining it as an exact replacement manifest with clear-on-omission behavior, which the schema's own 'Which fields to replace' text only implies. Other parameters (title, labels, openInfo, etc.) are left entirely to the schema.

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

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

States a specific verb and resource ('Update fields on a Google Business Profile location') and explicitly carves out scope by naming siblings that own other parts of the resource ('Hours and the service list have their own tools'). An agent can distinguish this from google_business_hours_update and google_business_service_list_update 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 a concrete prerequisite flow ('Read with google_business_location_get first') and names two categories of fields that must not be routed here because dedicated tools exist. It does not mention the adjacent google_business_attributes_update, so the alternative-routing advice is strong but not exhaustive.

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, non-idempotent, open-world and destructive behavior, so the safety profile is covered. The description adds genuine mechanism detail absent from the annotations: Google fetches the file server-side from media_url, so there is no upload step. It could go further on return values or rate limits, but the added fetch semantics are substantive.

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

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

Four tight sentences, front-loaded with the core action and mechanism, then constraints, then the one parameter caveat. 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?

For a creation tool with no output schema and full annotation coverage, the description supplies the operative constraints an agent needs to succeed (URL reachability, format, size, category intent). Minor omissions remain, such as what the call returns or whether the created media id is needed for later deletion, but nothing critical blocks 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 description coverage is 100%, so a baseline of 3 would apply, but the description meaningfully enriches key parameters: media_url must be publicly reachable https with concrete size/dimension limits, and category gets intent-based guidance beyond the enum list. This adds value over the schema's terse field descriptions.

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 uses a specific verb+resource ('Add a photo or video to a Google Business Profile location'), immediately distinguishing it from siblings like google_business_media_list and google_business_media_delete. An agent knows exactly what the tool does without opening the schema.

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

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

It gives real usage constraints ('Use category COVER or LOGO only when you intend to change the profile header or logo') and excludes invalid inputs (no short-lived signed URLs, no localhost). It stops short of routing the agent against alternatives such as media_list or media_delete, which is the only gap.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is largely covered. The description still adds value by emphasizing the removal is permanent (irreversible) and by imposing the cross-location ownership constraint, 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 the action and its effect front-loaded, followed by the parameter constraint. No filler or repetition of the tool name.

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 three-parameter delete tool with full annotation coverage and no output schema, the description supplies purpose, parameter provenance and a precondition. Return-value behavior is not described, but that is a minor gap for a straightforward deletion.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating that media_name originates from google_business_media_list and must belong to the target location, adding provenance and validation meaning the schema alone does not.

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 pairs a specific verb ('Permanently remove') with a specific resource ('a photo or video from a Google Business Profile location'), which cleanly separates it from sibling tools google_business_media_create and google_business_media_list 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?

It tells the agent where the required media_name comes from ('the full resource name from google_business_media_list') and adds a precondition ('must belong to this location'). There is no explicit when-not-to-use guidance, but the sourcing pointer is concrete routing context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one piece of context beyond that (these are profile-level photos, not post media). It says nothing about pagination behavior or result ordering, but with annotations carrying the safety burden a 3 is appropriate.

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 zero filler, and the core operation is front-loaded ahead of the disambiguating nuance. 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?

For a read-only list tool with a fully documented parameter schema and no output schema, the description covers what it is and how it differs from post media. Pagination and return-shape details are the only omissions, and the schema already hints at pagination, so it is adequate.

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 page_size, page_token, profile_id, and location_id are already documented in the schema. The description adds no parameter-level detail (e.g., how to obtain location_id or how page_token chains). Baseline 3 for a fully-documented schema.

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

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

States a specific verb and resource: 'List the photos and videos on a Google Business Profile location.' It adds a useful scope clarification that these are profile photos rather than media attached to a local post, which helps distinguish it from other media concepts. It doesn't explicitly differentiate from the closer siblings media_create/media_delete, but the verb makes the distinction obvious.

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 second sentence implies the usage boundary by contrasting profile media with local-post media, which helps an agent route correctly. However, there is no explicit 'use this when' statement, no alternatives named, and no mention of prerequisites or pagination workflow. Usage is only 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 cover readOnly=false, openWorld=true, idempotent=true and destructive=false, so the bar is lower, yet the description adds real substance: it explains the idempotency mechanism (keyed on location, uri, placeActionType, so a duplicate returns the existing link) and flags that accepted action types are category-dependent. It stops short of describing auth/permission 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?

Three tight sentences with the purpose front-loaded, followed by two behavioral caveats. No filler, and each sentence 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?

For a create tool with no output schema, the description covers purpose, the idempotent-return behavior, and the category constraint. It could go slightly further on return payload or permission prerequisites, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that place_action_type acceptance varies by category and by naming the (location, uri, placeActionType) key tuple that governs uniqueness. This clarifies behavior of two parameters that the schema alone only names.

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

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

States a specific verb and resource ('Add an action button') and names the target ('a Google Business Profile location'), so the operation is unambiguous. It does not explicitly reference the sibling tools (place_action_link_delete/update/links_list), though the create verb implicitly separates it from them.

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 by the create semantics — you call this to add a button — but there is no explicit 'use this when' or routing to the update/delete/list alternatives. The note that accepted place_action_type values vary by category is a useful caveat rather than true when-to-use guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds a consequence beyond the structured fields: the button stops showing on Search and Maps, telling the agent the deletion affects the public profile.

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

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

Two short sentences, front-loaded with the action and followed by the user-visible effect. Nothing is wasted and nothing is buried.

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

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

For a destructive three-parameter operation with an output schema absent but safety hints present, the description supplies the operation and its public consequence. What it lacks is guidance on irreversibility details or prerequisites, which keeps it short of perfect.

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 profile_id, location_id, and name are fully documented in the schema itself. The description adds no format or identity detail beyond that, 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?

States a specific verb ('Remove') and resource ('action link from a Google Business Profile location'), which cleanly separates it from the create/update/list place-action-link siblings. It never names those siblings, but the operation is unambiguous from the verb+resource pairing.

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 by the operation itself (removing an existing action link), but the description offers no explicit when-to-use, prerequisites, or pointer to sibling tools like google_business_place_action_link_update. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral detail not in structured data: Google omits the placeActionLinks key entirely when no links exist, which tells the agent how to interpret an empty 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?

Two lean sentences, front-loaded with the verb and resource, and the second sentence earns its place by explaining empty-result behavior. 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 simple list tool with 100% schema coverage and no output schema, the description is nearly complete; the empty-result caveat compensates for the missing return-format documentation. Slightly short of full marks because return ordering/shape is left to the agent to discover.

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 pagination and identifier parameters are fully documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline 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 ('List') and resource ('action links on a Google Business Profile location'), then grounds it with concrete examples ('Book online', 'Order online'). This cleanly distinguishes it from the sibling create/update/delete action-link tools.

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 by the read-only list nature of the tool and its clear name, but there is no explicit when-to-use guidance, no mention of alternatives (e.g., create/update/delete siblings), and no stated prerequisites beyond the required path parameters.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the provenance/ownership constraint on `name`, which is helpful, but says nothing about how `fields` replacement behaves or what happens to unlisted 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 sentences, zero waste, with the core action front-loaded and the identifier constraint immediately after. 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?

A mutation tool with full schema coverage and annotations carrying the safety profile needs little more; the description covers the key identifier caveat. It stops short of explaining replacement semantics or the return value, but no output schema exists to cover that.

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, but the description adds genuine meaning for `name` by tying it to the list tool and to this location's ownership. The replace-vs-merge semantics of `fields` remain documented only in the schema.

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

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

States a specific verb (update) and resource (action link on a Google Business Profile location), which cleanly distinguishes it from the create/delete/list siblings by name. It does not explicitly call out those alternatives, but the operation 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?

Provides one real precondition: `name` must be the full resource path obtained from google_business_place_action_links_list and must belong to this location. That is useful routing context, but there is no guidance on when to update vs. create/delete, nor on prerequisites like required scopes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the metadata.canModifyServiceList precondition, which is genuinely useful context, but it applies to editability rather than to this read operation and adds no return/format behavior.

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

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

Two short sentences with the action front-loaded and zero filler. The second sentence is terse, though its placement in a read tool's description is slightly off-topic.

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

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

For a simple two-parameter read tool with full schema coverage, complete annotations, and no output schema, the description is sufficient. Nothing critical for correct invocation is missing, though naming the update sibling would have completed the picture.

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?

Both parameters are fully documented in the schema (100% coverage, including the 'accounts/X/locations/Y' path format), so the schema carries the burden. The description adds nothing about profile_id or location_id; 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: 'Read the services offered by a Google Business Profile location.' An agent can identify it as the read counterpart to google_business_service_list_update, but the sibling is never named explicitly, so differentiation is inferred 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?

No when-to-use guidance or alternative mentioned. The clause 'Editable only when metadata.canModifyServiceList is true' is a condition governing mutation via the sibling update tool, not guidance for invoking this read tool, so it does not help the agent choose here.

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?

While annotations already flag destructiveHint=true and idempotentHint=true, the description adds substantial context beyond them: it explains the replacement is destructive (overwrites, not merges), names the exact failure condition (422 when metadata.canModifyServiceList is false), and specifies the accepted item shapes. This is genuinely useful behavioral disclosure.

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

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

Three dense, front-loaded sentences with zero filler: replacement semantics lead, item formats follow, failure condition closes. 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?

For a destructive mutation tool with no output schema, the description covers replacement semantics, item structure, the read-first workflow, and the failure mode. It omits any note on the response shape, but that is a minor gap against otherwise thorough coverage.

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

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

Schema coverage is 100% so the baseline is 3, but the description meaningfully exceeds it by detailing the two item shapes (structuredServiceItem with serviceTypeId from the location's category vs freeFormServiceItem with category/label), which the schema's generic 'accepted fields vary' text does not provide.

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 ('Replace the service list on a Google Business Profile location') with clear scope. An agent can immediately distinguish this mutation tool from the sibling google_business_service_list_get 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 strong usage context: 'This is a full replacement, not a merge — send the complete list,' and the schema note directs reading the current list first. It also states the 422 precondition tied to metadata.canModifyServiceList. It stops short of explicitly naming the get sibling as the read-first step, so it's clear but not exhaustively routing.

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

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

Annotations already declare readOnly/destructive/openWorld, so the safety profile is covered. The description adds genuine behavioral value by enumerating the returned fields and clarifying null semantics for scheduled_at, which is important given there is no output schema.

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

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

A single front-loaded sentence with no filler. The long field list is justified because no output schema exists to carry that 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 read-only list tool with no output schema, describing the entry shape and the scheduled_at null case is exactly the gap that needed filling. It still omits ordering/pagination semantics for 'recent', which keeps it short of 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?

Only one parameter (limit) and the schema documents it at 100% coverage with its default. The description adds nothing about limit, so the baseline of 3 applies.

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

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

States a specific verb ('List') and resource ('recent post jobs'), and the field enumeration makes the scope concrete. It is reasonably distinguishable from post_status/post_stats, though it never names those siblings 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?

No when-to-use guidance and no alternatives named. An agent cannot tell from the text whether to prefer this over post_status, post_stats, or queues_list; 'recent' is left undefined (how recent, ordering, pagination).

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

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

The description adds crucial behavioral details beyond annotations: it explains the default non-destructive behavior for platforms and the optional destructive action, which is consistent with destructiveHint=true and provides necessary nuance.

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 extremely concise—only two sentences—with no wasted words. It front-loads the primary action and follows with the key conditional 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?

For a tool with only two parameters and no output schema, the description covers all necessary information: the deletion action, the default scope, and the optional extended behavior. It is complete and sufficient.

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?

While schema coverage is 100%, the description adds value by explaining the default behavior of the delete_on_platform parameter and its effect, making the tool usage clearer.

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 clearly states it deletes a post from the database and distinguishes the default behavior (no platform removal) from the optional platform deletion. It is specific and contrasts with sibling tools like post_delete_on_platform.

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 when to use the optional delete_on_platform parameter, providing clear context. However, it does not explicitly compare with the sibling tool post_delete_on_platform, though the distinction is 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 indicate destructiveHint=true, but the description adds 'Async via background job' and clarifies it does not remove from database, which are useful behavioral traits beyond annotations.

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?

Single paragraph, front-loaded with key information. Every sentence earns its place with 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?

Covers scope, async nature, supported/unsupported platforms. No output schema, but for a deletion tool return values are less critical. Missing details on return or confirmation, but sufficient for typical use.

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%, but the description adds meaning for each parameter: explains how post_profile_id resolves to underlying profile and deletes across full thread, and clarifies scope narrowing. This adds value beyond the schema.

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

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

The description clearly states the action: 'Delete a published post from social media platforms WITHOUT removing it from the database.' This distinguishes it from siblings like 'post_delete' and lists supported platforms.

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?

Provides clear context on how to narrow scope via optional parameters (post_profile_id, profile_id, network) and states default behavior ('deletes from all published platforms'). Also lists unsupported platforms, but lacks explicit alternatives to 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the agent knows this is an irreversible public write. The description adds only capability scope, not the behavioral context an agent would want at call time, such as confirmation requirements, failure/partial-publish behavior, or the fact that publishing is public and cannot be undone.

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 verb and resource, followed by a compact feature enumeration. No filler or restatement of structured data.

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 nested platform objects and no output schema, the description is thin: it omits idempotency/dry-run semantics, mutual exclusions (schedule vs queue_id), and any sense of return value. The schema compensates for much of this, but the description itself does not.

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

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

Schema description coverage is 100%, so every parameter, including the rich nested 'platforms' object, is already documented. The description only names the 'platforms' parameter and repeats the X/Threads thread limitation, adding essentially no meaning 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+resource ('Publish a post to specified social media profiles') and enumerates the supported capabilities. It does not, however, differentiate itself from sibling post_publish_draft, which is left for the agent to infer from the name alone.

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 lists what the tool supports but gives no when-to-use guidance: no indication of when to prefer this over post_publish_draft, post_update, or a queue-based flow, and no mention of prerequisites such as connected profiles or required placements.

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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description reinforces write behavior with 'publish' but adds no new behavioral context such as permissions, rate limits, or side effects. It is adequate but does not exceed what annotations provide.

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 concise sentences front-loading the purpose and constraint. Every word earns its place; no unnecessary detail.

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

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

Given the tool's simplicity (1 param, no output schema), the description covers the core action and precondition. It does not mention return value or confirmation, but for a simple publish action, this is mostly sufficient. Slight room for improvement to describe expected outcome.

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

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

Schema description coverage is 100% with the parameter fully described. The tool description adds no additional meaning beyond the schema, so a baseline score of 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 clearly states the action 'publish' on 'draft post', and adds the condition that only draft status posts can be published. This distinguishes it from sibling tools like 'post_publish' which likely targets non-draft posts, and 'post_update' which doesn't change status.

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 explicitly says 'Only posts with draft status can be published using this endpoint', providing clear when-to-use guidance. However, it does not mention alternatives for non-draft posts or explicitly state when not to use this tool, missing a small opportunity to direct users to sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context by stating it 'Returns all matching snapshots,' implying no pagination, and mentions trend visualization and filtering support. This goes beyond what annotations provide.

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 that are clear and front-loaded. The first sentence states the core purpose, the second adds value about returns, and the third notes filtering options. Minor redundancy ('Get stats snapshots' vs 'Returns all matching snapshots'), but overall efficient.

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 should ideally explain the return format or stats fields. It only vaguely mentions 'trends over time'. The description adequately covers the input and basic behavior but lacks detail about what data is returned, leaving some gaps for a complex tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mentions filtering by profiles/networks and timespan, but does not add new meaning or clarify parameter format beyond the schema.

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

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

The description uses a specific verb ('Get') and resource ('stats snapshots for one or more posts'), clearly stating what the tool does. It distinguishes from siblings like 'profiles_stats' by mentioning filtering by profiles/networks and timespan, which is unique to this tool.

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

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

The description implies usage (when you need stats trends over time) but does not explicitly state when to use this tool versus alternatives like 'profiles_stats' or 'history_list'. No exclusions or when-not-to-use guidance is provided.

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?

With readOnlyHint/destructiveHint=false already covering the safety profile, the description adds genuinely useful behavioral detail: scheduled_at is null when unscheduled, and the response includes per-platform status with published URLs and media details. It stops short of error behavior (e.g., unknown post ID), 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?

A single front-loaded sentence stating purpose first, then the payload contents. The field list is long but earns its place because there is no output schema; slightly run-on but 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?

Because no output schema exists, the description correctly carries the burden of describing return values, which it does thoroughly. It covers the read-only nature via annotations and the main payload; only error/not-found behavior 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 description coverage is 100% for the single post_id parameter, so the schema fully documents its meaning and origin. The description adds nothing about the parameter beyond what the schema states – 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 a specific verb+resource ('Get status of a post by post ID') and enumerates the returned fields, so the agent knows exactly what it retrieves. It does not, however, explicitly distinguish itself from the similarly named sibling post_stats, leaving that differentiation 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?

The description gives no when-to-use guidance and never mentions the alternative tools (post_stats, post_publish, post_update). The only workflow hint comes indirectly from the schema ('Post ID from post.publish response'), not from the description itself.

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

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

Annotations already show destructiveHint=true, but description adds valuable context about partial updates and post status constraints. No contradiction.

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 fluff, critical information front-loaded. Every sentence adds value.

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 core behavior and constraints. No output schema, but parameters are well-documented in schema. Could mention error cases or return format, but not required for a simple update 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%, so baseline is 3. Description adds general partial-update guidance but no param-specific detail beyond 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?

Description clearly states 'Update an existing post' with specific constraints. Distinguishes from siblings like post_delete and post_publish.

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

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

Explicitly states when to use (only drafts or scheduled posts more than 5 min before publish) and provides update strategy ('only send fields you want to change').

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

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

Discloses async mechanics not visible in annotations: the call returns immediately with status 'pending', then a background job publishes to Google and transitions the status to 'published' or 'failed'. This is exactly the kind of eventual-consistency context an agent needs before retrying or polling, and annotations alone (destructive/openWorld/idempotent) would not convey it.

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

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

Three short sentences, all earning their place: purpose, the constraint, and the response lifecycle. The constraint is front-loaded before the async detail.

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 supplies the missing return-value semantics (pending → published/failed) and the required-input constraint. Nothing an agent needs to invoke and interpret the call correctly 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?

Schema coverage is 100%, so all three parameters are already documented, including parent_id's hashid/external_id forms. The description only reinforces that parent_id is required, adding no syntax or format detail beyond the schema — the expected baseline 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 ('Reply to an existing profile comment'), scopes it to Google Business reviews, and immediately rules out the sibling behavior of creating top-level comments. An agent can distinguish this from comments_create without opening either schema.

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

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

Explicitly states the when-not condition ('Top-level comments are NOT allowed — you can only reply to a review that already exists') and that parent_id is required. It does not name the alternative sibling tool (e.g. comments_create) for the top-level case, leaving that inference to the agent.

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

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

The description adds value beyond annotations (which include destructiveHint: true) by explaining the asynchronous nature of the deletion, the return value {accepted: true}, and the constraint that the underlying review cannot be deleted. No contradiction with annotations.

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 extremely concise with two sentences. The first sentence states the primary action, and the second adds important constraints and behavior. No unnecessary 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers the core behavior, async dispatch, and return value. However, it could mention error scenarios or prerequisites, but overall it is sufficient for an AI agent.

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 description enhances the schema by clarifying that comment_id must be 'Postproxy hashid OR external_id of YOUR reply to remove', emphasizing that it must be the user's own reply. This adds critical meaning beyond the schema's basic description.

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 clearly states the action 'Delete your reply to a profile comment', specifying the verb and resource. It distinguishes this tool by noting that it only removes the reply, not the underlying review, differentiating it from sibling tools like comments_delete.

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

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

The description provides clear context: it only deletes your own reply, not the underlying review (since Google does not allow businesses to delete reviews). It also mentions asynchronous dispatch. However, it does not explicitly guide when to use this versus other sibling tools like comments_delete or profile_comments_create.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds the detail about accepting external_id or hashid, but does not disclose error behavior, auth requirements, or other traits. Adequate but not enriched.

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, efficient sentence that conveys the action, object, and identifier options without redundancy. No filler or 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 simple read tool with two required parameters and no output schema, the description covers the essential: what it retrieves and how to identify the comment. It could optionally mention return format, but the annotations (readOnlyHint) imply it returns data. Slightly above adequate.

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% (both parameters documented). The description repeats the schema's note about comment_id being a hashid or external_id, adding no new meaning. Baseline 3 applies as 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 clearly states 'Get a single profile comment', specifying it can be a review or reply. It distinguishes from siblings like 'comments_get' by scoping to profile comments. The mention of identifier types further clarifies the tool's purpose.

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 implies when to use (when you need a single profile comment by its hashid or external_id), but lacks explicit guidance on when not to use or alternatives. No comparison to sibling tools like 'profile_comments_list' or 'comments_get' is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's read only nature is clear. The description adds value by noting that items may include nested replies and that reviews sync from Google twice daily, providing useful behavioral context beyond the annotations.

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 extremely concise—two sentences with no repetition or fluff. The first sentence states the core purpose, and the second adds important behavioral context. Every word 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 the tool's simplicity and the presence of annotations and full schema descriptions, the description is fairly complete. It mentions nested replies and sync schedule, which are important. However, it could have mentioned default ordering or pagination behavior beyond the schema, but overall it is sufficient.

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 all parameters. The description does not add new information about the parameters beyond what is in the schema descriptions. It provides context about the profile_id needing to be a google_business profile, but that is already in the schema description. Thus, baseline of 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 clearly states the tool lists profile-scoped comments, specifically Google Business reviews. It distinguishes from the sibling tool comments_list by explaining that reviews live on a location and cannot be reached via comments_list, making the purpose 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?

The description explicitly says when to use this tool (for Google Business reviews) and when not to (cannot be reached via comments_list). It also provides context about the sync schedule (twice daily at 06:00 and 18:00 UTC), which helps set expectations about data freshness.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine context beyond that: this only initiates a flow, the actual connection completes out-of-band when the user opens the URL, and the whatsapp onboarding omission changes behavior on the connect page.

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

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

Four sentences, front-loaded with the purpose and the returned-URL action, and each platform note earns its place. Slightly dense but 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 6-param initiation tool with no output schema and full annotation coverage, the description covers the flow's side effects, per-platform inputs, and how to consume the result. It could say a bit more about failure/expiry of the generated URL, but nothing essential is missing.

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

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

Schema description coverage is 100% and the per-parameter descriptions already state 'Required for telegram/bluesky' and detail the whatsapp enum, so the description largely restates the schema. It does add the omission-behavior nuance for whatsapp onboarding, but the baseline 3 applies when the schema carries the 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?

The description states a specific verb and resource ('Generate a URL to connect a new social media profile to a profile group') and immediately clarifies it initiates the OAuth/connect flow, so an agent can distinguish it from siblings like auth_status or profile_groups_list without opening the schema.

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

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

It gives clear conditional guidance per platform (bluesky → identifier+app_password, telegram → bot_token, whatsapp → optional onboarding) and explains what to do with the result ('should be opened by the user to complete the connection'). It does not name an alternative tool or state exclusions, 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.

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

Annotations already state readOnlyHint, idempotentHint, and destructiveHint=false. Description adds minimal behavioral context (scope: 'all groups accessible with your API key') but doesn't mention pagination, rate limits, or other traits.

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 first sentence states action, no wasted words. Every sentence adds value.

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 no parameters and no output schema, the description is fully complete: it explains what the tool does, what profile groups are, and how to use 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?

Zero parameters, so baseline is 4. Description adds meaning by explaining the purpose of the output, but no parameter details needed.

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?

Description clearly states 'List all profile groups accessible with your API key' – a specific verb and resource. It distinguishes from siblings by explaining that the returned group IDs can be used to filter profiles_list, a sibling tool.

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

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

Description provides clear context: explains profile groups are containers and instructs to use the returned id to filter profiles_list. This implies when to use this tool, though it lacks explicit exclusions or alternatives.

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 provide readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds that it lists profiles 'for posting', which gives some behavioral context but doesn't disclose additional traits like pagination or response format. With annotations covering the key behavior, a score of 3 is appropriate.

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 extremely concise: two short sentences with no filler. It is front-loaded with the essential information. Every word serves a purpose.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers the purpose and the sole filter adequately. It might lack details about the return format or default behavior when filter is omitted, but for a list tool with good annotations, it is nearly complete.

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

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

Schema description coverage is 100%, meaning the schema itself documents the single parameter well. The description mentions the optional filter but does not add meaning beyond what the schema provides. Baseline score of 3 is correct.

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

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

The description clearly states the action (list), resource (social media profiles), and purpose (for posting). It also mentions optional filtering by profile_group_id. This distinguishes it from sibling tools like profile_groups_list and others that deal with different resources.

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 describes when to use the tool (to list profiles for posting) and the optional filter. However, it does not explicitly state when not to use it or provide alternatives, though the context is clear enough for most use cases.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds substantive behavioral detail beyond the annotations: platform-specific return semantics, the Google Business resource-path format, and the WhatsApp metadata fields (display_phone_number, quality_rating, messaging_limit_tier, etc.). It does not describe pagination or general return shape, keeping it short of 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?

The core purpose is front-loaded in the first clause before the platform enumeration. The platform list is dense but each entry earns its place by defining a distinct meaning; the run-on single-paragraph form is slightly hard to scan but there is 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?

There is no output schema, so the description carries return-value burden, and it does so for the tricky cases (Google Business resource paths, WhatsApp metadata) plus states which platforms are supported. It omits a general description of the response shape and pagination, so it is strong but not exhaustive for a list 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?

With a single parameter and 100% schema description coverage ('Profile hashid'), the schema already fully documents the input and the description adds no further meaning for profile_id. The description's extra detail is about outputs/ids used downstream, not about this 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?

States a specific verb ('List') and resource ('available placements for a profile') and then disambiguates the abstract term 'placement' per platform, so an agent cannot confuse it with siblings like profiles_list or profile_groups_list. The per-platform enumeration removes all ambiguity about what a 'placement' is.

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