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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by noting that bare IDs are returned unless fields are requested, and it highlights auth and profile visibility constraints.

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 sentences, front-loaded with the primary action. Every sentence serves a purpose 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?

Given annotations and the presence of an output schema, the description covers auth requirements, privacy limitations, and basic output behavior. It is complete for a read-only 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?

Schema coverage is 75%, so baseline is 3. The description adds meaning for the 'fields' parameter by explaining the default return behavior. However, it does not elaborate on 'count' or 'order' beyond schema 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 clearly states the tool lists a user's friends, using a specific verb and resource. It distinguishes itself from siblings like vk_users_get by focusing on friends and mentioning output behavior.

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 that a user token is required and that it only works for profiles exposing their friend list. This provides context but does not explicitly compare with alternatives among 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 provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds token type limitation, which is useful behavioral 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?

Two sentences, each providing essential information without redundancy. First sentence states purpose, second sentence specifies token requirement—efficient and clear.

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?

Tool has output schema (implied), parameters documented, token requirement added. For a simple list tool, this is sufficient. No mention of pagination or sorting, but not necessary given the tool's simplicity.

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. Description does not add extra meaning beyond the schema, hence baseline score of 3.

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

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

Description clearly states verb (List), resource (communities), and scope (token owner belongs to). Distinguishes from siblings like vk_groups_search and vk_groups_get_by_id.

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?

Clearly states token requirement, specifying that user token is needed and community/service tokens won't work. Does not explicitly list alternatives but context is clear.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds that it can resolve short names to IDs and return specific fields, which provides 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?

Two sentences, front-loaded with the primary 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?

Given high schema coverage (100%) and presence of output schema, the description fully covers what the tool does, what inputs are needed, and the purpose. 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?

Both parameters have schema descriptions, but the tool description adds extra clarity: 'Comma-separated community IDs or short names (e.g. apiclub,vk). Positive and without the minus sign.' This goes 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?

Clearly states the tool looks up communities by ID or short name, resolves names to IDs, and reads fields like description, member count, and type. Distinguishes from siblings like vk_groups_search or vk_groups_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?

Explicitly says to use it for resolving names to IDs or reading group info before deciding next steps. Implies when to use, but does not explicitly list alternatives or exclusion conditions.

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 (readOnlyHint, idempotentHint) already indicate safe, idempotent behavior. The description adds value by revealing that hidden member lists return an access error instead of an empty list, and that output format depends on fields parameter.

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, no wasted words. The first sentence states the action, the second adds essential nuance. Perfectly 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?

Given the presence of an output schema (so return values are documented) and comprehensive annotations, the description covers all needed context: default output, parameter effects, and error behavior. It is complete for an agent to use 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%, but the description adds meaning beyond the schema: it clarifies the default output (bare user IDs) and the role of the 'fields' parameter. It also provides a crucial note about group_id format ('Positive and without the minus sign').

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 title 'List community members' and description clearly state the tool's purpose: listing members of a community. It specifies the output (bare user IDs or profiles) and distinguishes from tools like vk_groups_get by focusing on members.

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 does not explicitly state when to use this tool versus alternatives, but it provides a key behavioral note about hidden member lists causing errors. This implies caution but lacks direct usage guidance or exclusions.

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

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

Annotations indicate mutable, idempotent, non-destructive behavior. Description adds that the action may result in a join request if the community is closed. No contradictions with annotations. Could further detail side effects like notifications or 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?

Two concise sentences that front-load the main action and provide essential parameter guidance. No redundant information.

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

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

Given the tool's simplicity and presence of output schema and annotations, the description covers key aspects: purpose, parameter format, and behavioral modes. Lacks mention of authentication requirements or what happens if the user is already a member.

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 valuable context for group_id (positive, without minus sign) beyond the schema's description. The not_sure parameter is not enhanced, but the main parameter gains clarity.

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 the verb 'join' and the resource 'community', and distinguishes between direct join and sending a join request for closed communities. This differentiates from sibling tools like vk_groups_search or vk_groups_get_members.

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 context on when to use the tool (joining a community) and clarifies the group_id format (positive, without minus sign). It does not explicitly state when not to use or list alternatives, but the sibling tools are diverse and the purpose is clear enough.

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, idempotentHint, and non-destructive. Description adds that it returns matches with a total count, but does not disclose pagination behavior or rate limits. Given annotations, this is adequate but not exceptional.

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 sentences, zero wasted words, front-loaded with the main action. 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?

With output schema present, return values are covered. The description mentions optional narrowing and total count, covering most parameter intentions. However, it could briefly note that offset and count control pagination.

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 baseline is 3. The description lists several parameters (keyword, type, country, city, sort) but adds no additional meaning beyond the schema's own 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?

Description clearly states the verb 'Find' and resource 'communities', and specifies filtering by keyword, type, country, city, or sort order. This distinguishes it from sibling tools like vk_groups_get which retrieve groups by ID rather than search.

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 searching with optional filters but does not explicitly state when not to use this tool or mention alternatives among siblings (e.g., vk_groups_get for direct lookup). No exclusions or context for when to choose this over other group tools are 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 indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context about returning counts per reaction and parameter specifics (e.g., owner_id negative for community), going beyond the schema without contradicting 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?

Two sentences efficiently convey the tool's purpose and a key parameter detail. No waste, front-loaded with the core action.

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

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

Given the tool's complexity (6 params, 2 required, output schema, comprehensive annotations), the description covers the main purpose and essential parameter nuances. It does not discuss pagination but schema handles that. Adequate for a well-specified 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 descriptions cover 100% of parameters. The tool description adds minimal additional meaning (e.g., clarifying owner_id and item_id), but this information is already present in the schema, providing no significant extra value.

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 users who liked/reacted to an object with counts per reaction, using specific verbs and distinguishing from sibling tools that handle other operations like posts or users.

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 retrieving reaction data but lacks explicit guidance on when to use this tool versus alternatives or when not to use it. No comparison to sibling tools 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 the safe read-only, idempotent, non-destructive profile, so the bar is lower; the description still adds real value by disclosing the ordering (newest first), the payload shape (last message plus participant names), and the auth requirement (community token with the messages right).

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, each earning its place: scope and ordering first, then the filter use case, then the auth prerequisite. No filler or 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?

An output schema exists, so return values need not be explained, and the description still covers ordering, entry contents, the key filter, and the token scope required. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by giving the "unread" filter a concrete purpose (what is waiting for a reply), which the bare enum cannot convey. count and offset 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 (list conversations in the community inbox) plus what each entry contains and the ordering (newest first). It is clear what the tool returns, but it never names or contrasts with the closest sibling, vk_messages_get_history, which retrieves messages inside a single conversation.

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 concrete usage cue — use filter "unread" to see what is waiting for a reply — which is genuinely helpful. However there is no guidance on when to prefer this over vk_messages_get_history or vk_messages_mark_as_read, and no exclusions or prerequisites beyond the token note.

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, open-world. The description adds two traits not in structured data: the required auth scope ('community token with the messages right') and the result ordering (newest first). It doesn't cover pagination behavior, but that's minor against the annotation coverage.

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

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

Three short sentences, zero waste, front-loaded with the core action and ordering before the peer_id source and auth note. Each 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?

An output schema exists, so return values need not be described. With auth requirements, ID sourcing, ordering, and pagination parameters all covered across description and schema, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining that peer_id is the same user ID surfaced by vk_messages_get_conversations, telling the agent where to source the required value.

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), resource (messages of one conversation), scope (community inbox), and ordering (newest first). This clearly distinguishes it from vk_messages_get_conversations and vk_messages_send 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?

Tells the agent where peer_id comes from (vk_messages_get_conversations shows it), which is a concrete routing hint to the prerequisite sibling. It does not state when-not to use it or mention alternatives like send/mark_as_read, so it stops short of a 5.

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

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

Annotations already declare it is a non-read-only, idempotent, non-destructive, open-world operation. The description adds the useful scope detail that ALL messages in the conversation are affected, but discloses no auth requirements, rate limits, or side effects beyond that. Modest value over 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?

A single front-loaded sentence with the action first and the motivating example trailing. No wasted words and nothing buried that an agent needs.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers scope and a usage cue, which is sufficient for a one-parameter mutation tool, though it could say more about when not to call it.

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

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

Schema description coverage is 100% and the single peer_id parameter is documented as 'User ID of the person the community is talking to'. The description reinforces the 'one conversation' framing but adds no format or type detail 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?

States a specific verb+resource ('mark every message in one conversation ... as read') and scopes it to the community's inbox. It is clearly distinct in meaning from siblings like get_conversations or get_history, but it does not explicitly name a sibling to route the agent away 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?

The phrase 'e.g. after answering it' gives an implied usage scenario but offers no when-not guidance and names no alternative tool. Adequate but leaves the agent to infer when marking-as-read is or isn't appropriate.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so safety is largely covered. The description earns credit beyond that by disclosing the delivery-restriction behavior, the fact that a real human receives the message, the required user confirmation step, and the return value (new message_id). It does not cover failure modes or rate limits, so it falls 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 short sentences that are front-loaded with the core action, then the delivery constraint, then the human-impact warning and return value. No filler, and each sentence carries information the agent needs before invoking the tool.

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

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

For a mutation tool with annotations plus an output schema, the description covers the essential gaps: recipient eligibility, the confirmation requirement, and the returned identifier. Error handling and throttling behavior are absent, but the omission is minor given the structured data available and the presence of an output schema.

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

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

Schema coverage is 100%, so peer_id, message, reply_to and attachment are already documented, and the description adds no further syntax or semantic detail for any of them. The only indirect hint is 'the text' and the quoted-reply concept implied by 'answers', which is weaker than the schema's own wording. Baseline 3 is appropriate when the schema carries the full parameter burden.

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

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

States a specific verb and resource plus the sender's identity ('Send a message from your community to a person'), which distinguishes it from the read-oriented siblings like vk_messages_get_history and vk_messages_get_conversations. An agent can identify this as the only outbound-send tool in the set without opening any schema.

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

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

Gives a concrete eligibility condition for when this tool will actually work ('VK only delivers to people who have written to the community or allowed it to message them') and a workflow precondition ('show the user the text before sending'). It stops short of naming an alternative tool or explaining what to do when the recipient is not eligible, but the context it provides 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 indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds value by explicitly stating the token requirement and that it's the owner's feed, which are critical behavioral details 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 two sentences, front-loaded with the primary purpose, and every sentence adds essential information (what the tool does and token requirement). 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?

The tool has an output schema, so return values are covered. The description, combined with rich annotations and schema, provides sufficient context for a simple read operation. Minor gap: no explicit mention of pagination usage, but start_from parameter is described in schema as 'Pagination cursor'.

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 100% description coverage for all three parameters (count, filters, start_from). The description does not add any additional meaning or usage guidance for these parameters beyond what the schema already 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 'Read the token owner's own newsfeed', using a specific verb ('Read') and resource ('newsfeed'). It distinguishes from sibling tools like vk_wall_get, which is for wall posts, by specifying it's the personal feed of the token owner.

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 context by stating it requires a user token and is not public, which helps an agent understand when to use this tool (e.g., for personalized content) versus alternatives. However, it does not explicitly exclude other tools or provide direct comparisons.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to restate safety. It adds value by explaining special parameter values but does not disclose behaviors like pagination or authentication requirements beyond what annotations cover.

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-loaded with the main action. Every sentence adds essential information without fluff.

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 presence of output schema and full parameter documentation, the description provides enough context to use the tool. Minor gaps: no mention of default behavior when count is omitted, or pagination hints. Still, it is nearly complete for a simple 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?

Schema has 100% documentation for all 3 parameters, so the description adds minimal new meaning beyond what the schema already provides (e.g., repeating album_id options and owner_id sign). 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?

Description uses specific verb 'List' and resource 'photos from an album', clearly distinguishing from sibling tools like vk_wall_get (wall posts) or vk_photos_upload_wall (upload). It also specifies special album_id values.

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 context on album_id and owner_id formats, clarifying common usage scenarios. However, it does not explicitly compare with alternatives or state when not to use this tool, lacking exclusions.

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

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

Goes well beyond the annotations: it discloses the three-step VK upload, the returned attachment-string format (photo-1_2), the auth constraint (community tokens rejected with error 27), and the group_id sign convention. These are non-obvious operational facts the annotations (readOnly=false, openWorld=true) 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 dense sentences, front-loaded with purpose, then the return value, chaining target, parameter nuance, and auth caveat. No filler; 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?

Despite an output schema existing, the description still clarifies the returned attachment string's purpose and destination, plus the auth requirement and sign convention. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents image (URL or local path), caption, and the positive group_id convention. The description largely restates the schema's group_id note rather than adding syntax or format detail, so 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+resource ('Upload a photo so it can be attached to a post') and differentiates from siblings by naming the downstream consumers (vk_wall_post, vk_wall_edit) and its role as a pre-step. An agent can distinguish it from vk_stories_post_photo 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?

Clearly describes the workflow context: upload, then pass the returned attachment string to vk_wall_post or vk_wall_edit, and warns that a full user token is required (error 27). It gives strong positive guidance but does not explicitly exclude alternatives such as vk_stories_post_photo, leaving that 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the crucial behavioral detail that admin privileges are required, which is not captured in annotations. There is 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?

Two sentences are used: the first states the core purpose, the second adds a critical usage condition. No filler words; highly efficient and 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 read-oriented tool with an output schema, the description adequately covers what the tool does (reads statistics by period), the types of data (reach, visitors, activity), and the prerequisite (admin status). No additional behavioral details are needed given the annotations.

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 67% with descriptions for group_id and intervals_count. The description mentions 'by period: reach, visitors and activity' but does not elaborate on parameter syntax, formats, or constraints beyond what the schema provides. It adds marginal value.

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 reads community statistics (reach, visitors, activity) by period. It uses a specific verb ('Read') and resource ('community statistics'), and is distinct from sibling tools like vk_wall_get or vk_users_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?

The description provides necessary context: the token owner must be an administrator of the community. It does not explicitly state when not to use this tool or suggest alternatives among siblings, but the given condition 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 readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the write/network profile is covered. The description adds real behavioral value by disclosing the three-step server-side workflow (get upload server, upload, save), which explains latency and partial-failure risk. It does not mention retry/duplicate-publication risk, so it is 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?

Two sentences, no filler, with the core action and the multi-step nature front-loaded before the personal/community branch. 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?

An output schema exists, annotations cover the safety profile, and the schema fully documents parameters, so the description need not restate return values. It is complete enough to invoke correctly, with only the retry/idempotency caveat for a non-idempotent publish left implicit.

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 link_text enum, group_id sign convention and add_to_news default is already documented. The description only restates the personal-vs-community distinction that group_id's own description already carries, adding little beyond the schema.

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

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

States a specific verb and resource ('Publish a photo story on VK') and differentiates itself from the sibling vk_stories_post_video by naming the media type. The parenthetical upload flow further pins down what the tool actually does.

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 two modes of use: a personal story by default, or a community story when group_id is set. It gives clear context for the main branching decision but stops short of stating when-not to use it or naming alternatives for related actions.

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

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

Annotations already declare the write/open-world/non-idempotent profile, so the bar is lower, and the description usefully adds the internal three-step upload flow (get upload server, upload, save) that an agent should expect. It does not cover auth/scopes, failure/cleanup behavior if the mid-step upload fails, or rate limits, which would push it higher.

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 and the upload mechanism front-loaded before the scoping detail. 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 5-param publish tool with full schema coverage, annotations, and an output schema (so return values needn't be explained), the description covers purpose, mechanism and posting target. Only the absence of any error/partial-upload guidance keeps it from 5.

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 schema already documents video, group_id, link_url/link_text pairing and add_to_news. The description only restates the group_id personal-vs-community behavior already present in the schema, adding no new parameter meaning.

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

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

States a specific verb+resource ('Publish a video story on VK') and is immediately distinguishable from the sibling vk_stories_post_photo, which handles photos. It also names the mechanism (three-step upload, get server/upload/save), so the agent knows exactly what operation it triggers.

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 one routing rule – set group_id to post as a community, otherwise it's a personal story – which is real usage context. But it never names the alternative video/media tools or states when NOT to use this (e.g. photo stories or wall posts), leaving the agent to infer from the name.

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 read-only and idempotent hints; description adds behavioral context about checking profile closed status but doesn't elaborate further.

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-loaded with action, 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 low complexity, existing annotations, and output schema, the description fully covers purpose, usage, and parameter context 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% and description adds meaning: user_ids can be numeric IDs or screen names with example 'durov', clarifying usage 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?

The description clearly states the verb (look up), resource (VK users by numeric ID or short name), and distinguishes from siblings like vk_users_search.

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

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

Explicitly says when to use: to resolve a name to an ID before calling other tools or check if a profile is closed. Implicitly differentiates from search 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 indicate read-only, idempotent, non-destructive. Description adds what is returned (matches with total count) and pagination behavior, enhancing understanding.

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: first covers main action and optional filters; second covers return and pagination. Every word earns its place, 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?

With output schema present, description sufficiently covers search, filters, pagination, and return type. No missing information for effective 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 has 100% coverage with descriptions for each parameter. Description adds context by summarizing optional filters and pagination, slightly more than baseline 3.

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

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

Description clearly states the tool finds VK users by name with optional filters. It distinguishes from sibling tools like vk_users_get which retrieves specific users.

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

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

States optional narrowing by city, country, sex, or age, and mentions pagination. Lacks explicit when-not-to-use or alternatives, but adequate for typical search scenarios.

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 non-read-only, non-idempotent, and non-destructive. The description adds relevant context: owner_id must be negative for communities and positive for users, and it returns the new comment_id. These details go beyond the annotations and help the agent understand expected 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?

The description is extremely concise: two sentences that cover the core action, the key parameter nuance, and the return value. Every sentence is essential, and the structure is front-loaded with the primary 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 tool's simplicity, the description covers all necessary aspects: action, required parameters, owner_id convention, and return value. With an output schema present, the description does not need to detail return structure. It is sufficiently complete for a comment creation 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?

The input schema provides descriptions for all 3 parameters (100% coverage). The tool description adds extra context for owner_id, explaining the sign convention (negative for community). This enhances understanding beyond the schema alone.

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 ('Add a comment to a post'), identifies the resource (a post), and differentiates from sibling tools like vk_wall_post (create a post) or vk_wall_delete. The mention of owner_id convention and return value provides additional clarity.

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 implicitly indicates when to use it (to add a comment) but does not explicitly state when not to use it or compare with alternatives. For example, it doesn't contrast with vk_wall_edit or vk_wall_post for creating comments on posts.

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

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

Annotations already mark destructiveHint=true. Description adds that deletion 'cannot be undone', reinforcing the destructive nature and clarifying context (owner_id negative for community). 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 concise sentences: first states core action, second adds essential nuance. No fluff.

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?

Simple two-parameter tool with output schema present (though not shown). Description sufficiently covers deleting a post; no obvious 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 description coverage is 100%, baseline 3. Description adds meaning by explaining owner_id sign convention (negative for community) and default behavior (token owner), going 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?

Description clearly states the action ('Delete a post') and resource ('from a wall'), and specifies the owner_id convention. It distinguishes from sibling tools like vk_wall_get, vk_wall_post, vk_wall_edit by focusing on 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?

Description mentions irreversibility and owner_id sign convention, but does not explicitly state when to use this tool vs alternatives (e.g., for permanent removal vs hiding or editing), nor provide exclusion criteria.

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 context beyond annotations: it explains that editing overwrites previous content, which aligns with the destructiveHint=true annotation. It also clarifies owner_id conventions. 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 zero wasted words. The purpose is front-loaded, and the critical behavior is stated immediately.

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

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

For an edit tool with good annotations and full schema, the description is sufficient. It covers the main behavioral aspects. Minor gaps like required permissions or error handling are acceptable given the simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the message parameter expects the full new text, not an addition. This clarifies the semantics beyond the schema 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 uses the specific verb 'replace' and identifies the resource as 'an existing post'. It clearly distinguishes from siblings like vk_wall_post (create new) and vk_wall_delete (remove).

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

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

It provides a key guideline about overwriting content: 'pass the full new text rather than an addition.' This explains how to use the tool correctly. However, it does not explicitly state when to choose this tool over alternatives, so not a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by noting that posts are returned newest first, and that each post carries likes, reposts, comments, and views. It also explains the sign convention for owner_id, which is not in 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 two compact sentences with no redundant words. It front-loads the main action and then provides essential details in the second sentence.

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 that all parameters are optional, schema coverage is full, an output schema exists, and annotations cover safety, the description completes the picture by explaining ordering, target selection, and output contents. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond schema by explaining the dual usage of domain and owner_id, and emphasizing the engagement metrics each post includes. This clarifies parameter interplay.

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 reads posts from a wall, specifies the resource (user or community), and contrasts with sibling tools like vk_wall_post or vk_wall_delete. It explicitly says 'Read posts from a user or community wall, newest first.'

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 tool: to read posts. It provides guidance on how to specify the target using domain or owner_id, with a clear rule for positive/negative values. It does not explicitly exclude non-use cases, but the context from sibling names implies it is for reading, not writing.

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, openWorldHint, idempotentHint, and nondestructive behavior. Description adds the specific ID format and the use case of re-reading, which complements the high annotation coverage without contradicting 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?

Two sentences, front-loaded with 'Fetch', no wasted words. Example and use case are included efficiently.

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 output schema present and simple parameters, the description adequately covers the tool's purpose and usage. The example and guidance on re-reading provide sufficient context 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 descriptions cover both parameters fully (100% coverage). The description reiterates the ID format and comma separation, which adds no new meaning beyond the schema. 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?

Description clearly states 'Fetch particular posts by their full IDs', providing a specific verb and resource. The example ID format and mention of re-reading posts distinguishes it from siblings like vk_wall_get (which likely lists posts) and vk_wall_post (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?

Description explicitly advises using it to 're-read a post you already know about', giving clear context. It does not explicitly list exclusions, but the sibling set implies alternatives for listing or 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 indicate readOnlyHint=false (mutation), destructiveHint=false, idempotentHint=false. The description adds value by explaining idempotency prevention via 'guid' parameter, the behavior of posting on behalf of community vs personal, and the return value (new post_id). No contradictions 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 three sentences, front-loaded with the main action. Each sentence provides essential guidance without redundancy. 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?

Given the complexity (6 parameters, 1 required) and presence of an output schema, the description covers key scenarios: community vs personal posting, attachment handling, scheduling. Returns important info (post_id). Rate limits or permissions are not discussed, but annotations and context signals (destructiveHint=false) partially address safety. Overall complete for selection and invocation.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds critical semantic context: the meaning of negative owner_id with from_group, the source of attachment strings (vk_photos_upload_wall), and the scheduling constraint (publish_date within 2 weeks via schema). This goes beyond raw schema definitions.

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 a post on a wall') and specifies the resource ('a wall'). It distinguishes from siblings like vk_wall_get, vk_wall_delete, vk_wall_edit, vk_wall_create_comment by focusing on posting. Additional details on community vs personal posting further clarify scope.

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

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

The description provides explicit guidance for posting in a community (owner_id with minus sign and from_group true) and for attaching media via vk_photos_upload_wall. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for typical use cases. Lacks explicit 'when-not-to-use' but still strong.

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