XPlanner

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description simply restates that a cancellation occurs. It adds no extra context about irreversibility, side effects, whether the post is deleted or merely unscheduled, or any prerequisites.

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 single sentence is short and free of filler, and its core verb+object are easy to parse. However, it essentially duplicates the title without adding new information, so it is under-specified rather than genuinely informative.

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 no output schema, the description does not clarify the operation's effect (delete vs cancel vs unschedule) or what the tool returns. The idempotency annotation helps but is not a substitute for stating behavior.

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

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

Schema description coverage is 0% and the description does not mention the required 'id' parameter at all. With no parameter documentation in either schema or description, an agent must guess that the id refers to the scheduled post.

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 clear action ('cancels') and resource ('a scheduled post'), and the word 'scheduled' distinguishes this from general post operations such as delete_post. It does not explicitly name sibling tools, so it stops short of a full 5.

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

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

No guidance is given on when to use this versus siblings like delete_post or publish_post. The only contextual hint is 'scheduled', which implies scope but does not state 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 indicate this is not read-only, is idempotent, and not destructive. The description adds the account-scope and optional media selection, which is helpful. However, it does not disclose side effects such as whether the idea is marked as used, what happens to the idea after conversion, or what the return value is. With annotations lowering the bar, this is minimally adequate but not rich.

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

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

Two compact sentences with the primary action and key optionality front-loaded. No filler or repetition, making it 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?

For a tool with two parameters and no output schema, the description covers the core action but omits important practical details: it does not state whether the tool returns the new draft post, what happens to the original idea, or any prerequisites beyond having an idea ID. An agent may be uncertain about the outcome, which is a notable gap given annotations do not clarify return behavior.

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

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

Schema coverage is 0%, so the description must compensate. The only parameter-specific information is that mediaAssetIds is an optional subset from the idea's media pool. The ideaId is not explained beyond being an identifier of an idea, and no guidance is given on how to obtain it or its validity. The description adds minimal context beyond the schema's field 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?

The description uses a specific verb ('converts') and direct resource ('idea to draft post'), and specifies the account context. It clearly distinguishes from generic post creation by tying it to an existing idea, and the optional media subset is mentioned, giving a complete picture of the tool's function.

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 versus sibling tools like create_post or update_idea. It does not state prerequisites (e.g., idea must exist, belong to user) or exclude scenarios where this tool is inappropriate. The usage context is only implied, not explicit.

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 annotations already declare readOnlyHint=false (mutating) and idempotentHint=true, but the description adds no additional behavioral context. It says 'connects to an X account' without explaining what that entails (e.g., authorization requirements, side effects on the account). The description neither contradicts the annotations nor enriches them, offering minimal transparency beyond what is already structured.

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 front-loads the core action and mentions the account connection. However, it is so brief that it may be under-specifying rather than elegantly concise, which is why it doesn't reach a 5.

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 six parameters and no output schema, the description is incomplete. It omits important context such as how the idempotencyKey should be used, the meaning of 'connects to an X account', and any prerequisites or return values. The agent lacks sufficient guidance to invoke the tool correctly, especially for edge cases like duplicate names or validation rules.

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 schema provides descriptions for 4 of 6 parameters (67% coverage), including accountId, color, order, and isPinned. The description itself adds no parameter-level information, so it relies entirely on the schema. Since coverage is high, the baseline of 3 is appropriate; the description does not compensate for the undocumented parameters (name, idempotencyKey) but doesn't need to given schema coverage.

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 ('creates a new folder') and identifies the resource (folder) and the associated account connection. It distinguishes itself from sibling folder tools (get/list/update/delete) by specifying the creation verb, and the title reinforces this. However, it doesn't add any specific details about what a folder is or its purpose beyond the bare action, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that creating a folder is a prerequisite for other operations, nor does it reference sibling tools like xplanner_update_folder or xplanner_delete_folder for subsequent actions. No exclusions or conditions are given, leaving the agent to infer usage from the name alone.

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

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

Annotations already cover readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description only needs to add context beyond those. It does add that the idea is linked to an X account, which is useful, but it does not describe side effects, validation, or what happens if the account is missing. 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 short sentences, front-loaded with the verb and object, and no filler or repetition of schema/annotations. Every word carries meaning.

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

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

Despite a 7-parameter write operation and no output schema, the description provides only a minimal high-level statement. It lacks usage context, details about optional parameters (folder/media/idempotency), and any indication of return behavior. The annotations cover safety, but the tool's full calling context is not complete.

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

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

Schema description coverage is only 57%, and the description does not help fill the gaps: folderId, mediaAssetIds, and idempotencyKey remain undocumented in both schema and description. The 'Bir X hesabına bağlanır' phrase only reinforces accountId, which the schema already documents. A write tool with seven parameters needs more semantic support.

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 concrete action: 'Yeni bir fikir notu kaydeder' (saves a new idea note) and adds the distinguishing account relationship 'Bir X hesabına bağlanır'. This clearly separates it from sibling tools like create_post, create_folder, or update_idea, and the word 'yeni' signals creation rather than mutation.

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 given about when to choose create_idea over alternatives, nor any exclusions or prerequisites. The description simply states what the tool does; it does not mention that this is for creating ideas only and should not be used for posts/folders, nor when conversion to post might be preferred.

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 readOnlyHint=false. The description adds useful context that this creates a signed address for direct upload rather than uploading content itself, and that registration is required afterward. It does not disclose URL expiry, permission requirements, or failure modes, but the annotations cover the core safety 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 sentences with no filler: the first states the purpose, the second states the required follow-up action. The information is front-loaded and 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?

The description explains the two-step workflow and names the follow-up sibling, which is helpful. However, there is no output schema and no mention of the response shape, upload method, or parameter roles, so the agent must infer several important details from the schema alone.

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 0%, and the description mentions no parameters at all. The purpose statement weakly implies fileName, mimeType, and bucketId relate to the upload, but it does not explain required accountId, objectPath, or idempotencyKey. With six parameters, this is a significant gap.

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

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

The description clearly states the specific verb (oluşturur), the resource (imzalı adres for XPlanner storage), and the direct-upload purpose. It also distinguishes itself from the sibling xplanner_register_media_asset by explaining that registration happens after upload, so an agent can tell the tools apart.

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 gives the workflow: create the signed address, upload the file, then call xplanner_register_media_asset. This is clear contextual guidance and names the relevant sibling, making the tool's role in the process unambiguous.

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, idempotentHint=true, destructiveHint=false. The description complements this by disclosing the permission requirement for publish_now (posts:publish), the outcomes of each mode (saved as draft, scheduled, or added to publish queue), and the mandatory prerequisite calls. No contradiction with annotations; it adds useful behavioral context beyond the structured hints.

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 concise and front-loaded: it states the purpose first, then the flow prerequisites, mode semantics, and a compatibility note. Each sentence carries essential information with no redundancy. The structure is logical 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?

Given the complexity (11 parameters, nested publishTargets, no output schema), the description covers core usage (modes, prerequisites, permissions) but omits details on optional parameters like mediaMetadata, idempotencyKey, and workspaceId, and does not describe the return format or error scenarios. It is adequate for basic operation but incomplete for a tool of this complexity.

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 55%, so the description adds value by explaining mode behavior, the socialSetId+publishTargets flow, and text handling (per-platform limits, textOverride). It also clarifies accountId as backward-compatible. However, parameters like mediaMetadata, idempotencyKey, and workspaceId have no description in either the schema or the description, leaving gaps. Still, the description meaningfully enhances the most critical parameters.

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 creates posts for X, LinkedIn, and Threads, with explicit modes (draft, scheduled, publish_now). It uses a specific verb 'creates' and resource 'posts', and distinguishes itself from siblings like xplanner_create_idea and xplanner_publish_post by focusing on post creation. The platforms and modes are 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 instructs to call xplanner_list_social_sets and xplanner_get_platform_capabilities first, provides mode selection logic (draft default, scheduled with scheduledAt, publish_now with permission), and clarifies old vs new client usage (accountId vs socialSetId+publishTargets). This gives clear when-to-use guidance and even mentions prerequisites.

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, idempotentHint=true, and openWorldHint=true. The description adds the key behavioral context that deletion is permanent ('kalıcı olarak') and that explicit user consent is required. This goes beyond the annotations by clarifying the irreversibility and the consent requirement, which is valuable for an agent deciding whether to invoke the 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?

The description is a single, concise sentence that front-loads the core action ('Bir klasörü kalıcı olarak siler') and adds the critical consent condition. Every word earns its place; there is no redundancy or 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 single-parameter delete tool with annotations covering destructive/read-only/idempotent hints, the description is largely complete. It states permanence and consent, which are the key behavioral facts. It doesn't mention return values, but there is no output schema, and for a delete operation the absence of a return description is a minor gap. The sibling list provides context that this is one of several delete tools, but the description doesn't need to enumerate all alternatives.

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 0%, so the description carries the burden for parameter semantics. However, the description does not explain the 'id' parameter beyond what the schema provides (type string, format uuid). The schema already specifies the format and pattern, so the description adds no additional meaning about what the id refers to (e.g., folder ID). Baseline 3 is appropriate because the schema is self-explanatory for a single UUID parameter, but the description could have clarified that id is the folder identifier.

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: 'Bir klasörü kalıcı olarak siler' (permanently deletes a folder). It clearly identifies the action and target, and the destructive nature is explicit. It doesn't explicitly distinguish from sibling delete tools (delete_idea, delete_post, delete_media_asset), but the resource is named, so an agent can infer the target.

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 context by stating the user must have explicitly requested this destructive operation, which serves as a cautionary guideline. However, it doesn't provide explicit when-to-use vs alternatives, such as noting that update_folder might be preferred for non-destructive changes or that delete_idea/delete_post are for other resource types. The condition 'Kullanıcı bu yıkıcı işlemi açıkça istemiş olmalı' is a clear prerequisite but not a full usage guide.

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 readOnlyHint=false. The description adds that deletion is permanent and requires explicit user consent, providing useful behavioral context beyond what annotations 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?

The description is two concise sentences with no redundant information. The core action is front-loaded, and the warning about user consent is succinctly stated.

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 delete operation with one required parameter, the description covers key context: permanence and the requirement of explicit user request. It omits guidance on the 'id' parameter, but the schema's UUID format and the tool name mitigate this gap.

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

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

Schema coverage is 0%, and the description does not mention the 'id' parameter at all. While the tool name suggests the id identifies the idea, the description fails to explain how to specify which idea to delete, leaving the agent to infer from 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: permanently deletes an idea. It specifies the resource type (idea) and the permanence, distinguishing it from sibling delete tools for folders, posts, and media assets.

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 a clear usage condition: the user must have explicitly requested this destructive operation. This implies it should only be used when the user has asked to delete an idea, though it does not explicitly contrast with alternative delete 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 destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that. It adds value by specifying 'kalıcı olarak' (permanently), which is more specific than the generic destructive hint, and by emphasizing the requirement of explicit user consent. However, it does not describe side effects, reversibility, or what happens to related data beyond permanence. The added context is useful but not extensive.

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

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

The description is two short sentences, front-loading the core action and then adding the critical usage requirement. It contains no filler, repeats no schema or annotation information, and is appropriately sized for the tool's simplicity. 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?

For a tool with one parameter and no output schema, the description covers the essential aspects: the action, its permanence, and the explicit user request requirement. It does not mention what happens on success or failure, but that is not necessary given the lack of an output schema. The description is complete enough for an agent to decide when to use it, though it could benefit from a brief note on the id parameter (which is already scored low in parameter semantics).

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 0%, meaning the parameter 'id' has no description in the schema. The description itself does not explain what the 'id' refers to or any constraints on it. While the tool name implies the id is the media asset's identifier, the description does not explicitly state this. With no parameter documentation in either the schema or the description, the agent has to infer the meaning, which is a significant gap for a single-parameter tool.

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: 'Bir medya varlığını kalıcı olarak siler' (permanently deletes a media asset). The verb 'delete' and resource 'media asset' are specific, and it distinguishes from sibling delete tools (delete_folder, delete_idea, delete_post) by naming the resource type. It also adds the qualifier 'kalıcı' (permanent), which reinforces the intended effect.

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 one usage constraint: 'Kullanıcı bu yıkıcı işlemi açıkça istemiş olmalı' (user must have explicitly requested this destructive operation). This tells the agent when it is appropriate to invoke the tool, but it does not mention alternatives or when not to use it. Given the presence of sibling delete tools, some guidance on distinguishing them would be valuable, but the description is not entirely lacking.

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 readOnlyHint=false. The description adds value by emphasizing 'permanently' (beyond mere destructive) and the explicit user-consent requirement, which are not captured in annotations. It does not contradict 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 short sentences, no filler, and the core purpose is front-loaded. The second sentence provides a necessary safety condition. It is appropriately concise without being under-specified.

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

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

For a simple one-parameter delete operation, the description covers the essential purpose and a critical usage constraint. It does not mention return values or side effects, but the absence of an output schema and the simplicity of the operation make this acceptable. Annotations cover idempotency and destructiveness.

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 schema has no description for the only parameter 'id' (coverage 0%). The description does not explain that 'id' identifies the post to be deleted, leaving the agent to infer it. Since the tool has just one parameter, this is a notable omission that the description should have clarified.

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 clear verb ('deletes') and resource ('post') with the key qualifier 'permanently', which distinguishes it from a mere cancel or soft-delete. It does not explicitly name a sibling tool, but the permanence makes it distinct from xplanner_cancel_post and other delete 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?

The description adds a clear usage condition: 'the user must have explicitly requested this destructive operation.' This tells the agent when it is appropriate to invoke the tool. However, it does not mention any alternative tools (e.g., cancel_post for scheduled posts) or conditions when it should NOT be used.

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 openWorldHint=true, so the description does not need to repeat safety. The description adds the behavior of retrieving a single folder, but does not disclose error handling or return format. With annotations covering the safety profile, this is adequate but not rich.

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 with no unnecessary words. It states the action and scope immediately, making it efficient for an agent to parse.

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 get operation with one required parameter and annotations indicating read-only behavior, the description is sufficiently complete. It does not describe the return format, but with no output schema, this is not a critical gap.

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

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

Schema description coverage is 0%, but the description mentions 'by id', which clarifies that the parameter is the folder identifier. This adds minimal meaning beyond the schema's type/format constraints, which is acceptable for a single required parameter.

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

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

The description 'Tek bir klasörü id ile getirir' (Gets a single folder by id) states a specific verb (get), resource (folder), and the identifying parameter (id). It clearly distinguishes from siblings like list_folders (which retrieves multiple) and create/delete/update folder operations.

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 the purpose is clear: use when you have a specific folder id. It does not mention exclusions or alternatives, but the context is implied by the verb and resource.

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 openWorldHint=true, so the agent knows this is a safe read operation. The description's 'getirir' (fetches) is consistent with these annotations, adding no contradiction. It adds minimal behavioral context beyond what annotations provide — essentially just that it retrieves a single record by id.

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 short sentence with no filler. The core action and resource are stated efficiently, and nothing is wasted. It is appropriately sized for the simplicity of 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 simple single-parameter, read-only tool with no output schema, the description covers the essential information an agent needs: what it does and how it is invoked. Combined with the annotations (readOnly, openWorld) and a fully validated uuid schema, little else is needed 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 0%, so the schema itself carries no descriptive text for the id parameter. The description does reference 'id ile' (by id), confirming that the id is the lookup key. For a single required uuid parameter, the semantics are mostly self-evident from the schema's format/pattern constraints, and the description adds a small amount of clarifying 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 states a specific verb (getirir/get), a specific resource (fikri/idea), and the lookup mechanism (id ile/by id). This is clear and unambiguous. However, it does not differentiate from sibling get tools like xplanner_get_post or xplanner_get_folder — though the name itself carries the resource distinction.

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 guidance on when to use this tool versus alternatives such as xplanner_list_ideas or the other get_* tools. No when/when-not conditions or alternative references are provided, leaving the agent to infer usage from the name alone.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context: the returned limits are stated as 'güncel' (current), implying they may change and should be fetched fresh rather than assumed. It also scopes the behavior to specific platforms. No contradictions with annotations were found.

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, each earning its place: the first states the operation and scope, the second gives the triggering use case. There is no redundancy or 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 no-parameter, read-only capability fetch, the description provides the essential context: which platforms, what kind of limits, and when to call it. The only minor gap is that without an output schema the exact return structure is not described, but the declared resource ('text and media limits') is specific enough for an agent to invoke and interpret the call.

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

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

The tool has zero parameters seized, and the schema is empty, so there are no parameter semantics to document. The rubric gives a baseline of 4 for zero-parameter tools, and the description adds no missing param-related 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 uses a clear verb ('getirir'/'fetches') with a specific resource: current text and media limits for X, LinkedIn, and Threads. It also names the precise use case, which differentiates it from the other get/list tools in the sibling set.

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 states when to use this tool: before producing content or preparing publishTargets. It does not mention when not to use it or name alternatives, but there is no obvious sibling alternative for platform capabilities, so the stated usage context is sufficient.

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 openWorldHint=true, so the description carries no extra behavioral burden. It adds no additional context about return values, error handling, or side effects beyond the basic operation, which is already covered by 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 a single, concise sentence with no redundancy. It is front-loaded with the essential information and contains zero 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 getter with one well-defined parameter and annotations covering read-only behavior, the description is adequate. It does not explain return format, but no output schema is provided, and the operation's purpose is clear. It could mention what happens if the post is not found, but that is a minor gap.

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

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

Schema description coverage is 0%, so the description should compensate. It does mention 'by id' (id ile), which clarifies that the 'id' parameter is the post identifier. However, it adds little beyond what the schema already defines with format and pattern, and does not explain the parameter's semantics in more depth.

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 (getirir - fetches) and the resource (single post by id). It distinguishes from sibling list_posts by specifying 'single' and 'by id', and from other getters (folder, idea) by naming 'post'.

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: use this when you need a single post by id. However, the description does not explicitly mention alternatives or when not to use it, though the tool name and sibling context make it fairly obvious.

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, covering the non-mutating behavior. The description adds contextual detail about 'current period' and specifies the returned data (counts and limits), but it does not disclose other behavioral aspects such as authentication requirements, response size, or potential errors. Since annotations already carry the safety profile, the description contributes modestly but not extensively beyond them.

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, compact sentence that conveys the essential purpose without any extraneous words. It is front-loaded with the resource and data type, making it efficient for an agent to parse.

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 (zero parameters, no output schema, read-only annotations), the description fully specifies what the tool retrieves (counts and limits for the current period). There is no missing information that an agent would need to call it 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain any parameters, and the baseline for zero-parameter tools is 4. It does not add parameter information, but none is required to use the tool correctly.

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 resource ('current period's post/idea counts and plan limits') and the implied action of retrieving usage data. It distinguishes itself from sibling tools by focusing on usage/limits rather than specific content entities like folders or posts. However, it lacks an explicit verb like 'get' in the description itself (though the title includes 'getir'), and the scope (e.g., user-level vs workspace-level) is not stated, which keeps it from a 5.

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

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

There is no guidance on when to use this tool versus alternatives. While it is the only tool related to usage/limits among the siblings, the description does not explicitly state circumstances for selection, nor does it mention any exclusions or prerequisites. An agent would have to infer its applicability based solely on the resource 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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful runtime behavior: there is no pagination and all accounts are returned in one response. It does not detail the full record shape or error behavior, but those are less critical for a simple read-only list.

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 cover purpose, sibling alternative, id reuse, and pagination behavior with no filler. The key exclusion (list_social_sets) is front-loaded and clearly stated.

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

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

For a zero-parameter, read-only list tool, the description is complete enough: it states what is listed, when to use the sibling instead, what the returned id is for, and that the response is unpaginated. No critical invocation or interpretation detail 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?

The schema has zero properties, so the baseline is 4. The description adds no parameter details because there are none, but it does clarify that the returned id can be used as accountId, which gives useful semantic context about the output.

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 action: 'lists backward-compatible X account records.' It clearly distinguishes itself from xplanner_list_social_sets by naming the alternate for multi-platform posts, so an agent can disambiguate without inspecting schemas.

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 explicit routing guidance: for multi-platform posts, use xplanner_list_social_sets instead. It also explains when the returned id should be reused as accountId in idea, folder, and media flows, which is concrete selection and integration 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 openWorldHint=true, covering the safety profile. The description adds filter context but does not disclose additional behavior such as pagination semantics, result ordering, or open-world result characteristics. There is no contradiction with 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 two short, front-loaded sentences with no filler. It states the core action first and the filtering capability second, making it 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?

For a simple list operation with read-only/open-world annotations, the description is minimally viable: it covers purpose and filters. However, there is no output schema and no mention of pagination parameters (limit, cursor), so an agent may not know how results are paged or what defaults apply.

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 paraphrases the two documented filters (account and name) which map to accountId and query, adding marginal natural-language value. However, limit and cursor are not explained anywhere, and with 50% schema description coverage the description does not fully compensate for the undocumented parameters.

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 and resource: 'Klasörleri listeler' (lists folders) and that results can be filtered by account and name. It is distinguishable from sibling tools like get_folder, create_folder, and delete_folder by the listing action and filter scope, though it does not explicitly contrast itself with 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 intended use is implied: call this tool to list folders and optionally filter by account or name. However, there is no explicit guidance about when to prefer it over alternatives such as get_folder or list_workspaces, and no exclusions or prerequisites are 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 annotations include readOnlyHint=true, so the description does not need to repeat that it is a safe read operation. The description adds the filter capability, which is a behavioral aspect but not a disclosure of side effects or constraints. It does not mention pagination behavior, rate limits, or any other operational details, but given the annotation coverage, 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?

The description is concise, consisting of two short sentences. The first sentence states the primary action (lists idea notes) and the second adds the filtering capabilities. There is no unnecessary text, and the most important information 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?

The tool has 4 parameters, including pagination parameters (limit and cursor), but the description does not explain how pagination works or that cursor is used for pagination. There is no output schema, and the description does not mention return format or ordering. An agent would lack critical information to correctly use the tool, especially the cursor parameter, making the description incomplete for a list tool with 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?

The schema covers 50% of parameters with descriptions: folderId and accountId have descriptions, while limit and cursor do not. The description reinforces the meaning of folderId and accountId by stating the tool can be filtered by account and folder, but it does not add any information about limit or cursor. Since the description partially compensates for the missing schema descriptions but not completely, a 3 is warranted.

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 idea notes ('Fikir notlarını listeler') and mentions the filtering options by account and folder. This is a specific verb+resource combination that distinguishes it from sibling tools like xplanner_list_posts or xplanner_list_folders, so an agent can easily identify its 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 provides context on what the tool does and that it can be filtered, but it does not explicitly state when to use it over alternatives or mention any exclusions. The usage is implied from the name and the filter capabilities, but there is no direct guidance on choosing this tool versus other list tools in the sibling set.

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 and openWorldHint annotations already covering the safety profile, the description adds meaningful context: it identifies the asset types included and explains that the returned storageRef is intended for use as mediaRefs in a post. This goes beyond the annotations by clarifying the integration behavior, though it does not disclose pagination or ordering 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 two concise sentences with no redundancy. The primary action and resource are front-loaded, and the second sentence adds a valuable integration detail without bloating the 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?

The tool has four parameters including pagination controls and an optional workspaceId, and no output schema exists, yet the description only mentions storageRef and account context. Missing details about cursor/limit behavior, workspace scoping, and the full response shape leave an agent under-equipped to invoke the tool 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 only 25%, so the description must compensate, but it does not explain limit, cursor, or workspaceId semantics. The phrase 'XPlanner account context' loosely maps to accountId, but the pagination parameters and workspace scoping are left undocumented in both the schema and the 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 specifies the action ('lists'), the resource ('registered images, GIFs and videos'), and the context ('XPlanner account context'). It also differentiates from sibling listing tools by naming media assets specifically and explains the downstream use of the returned storageRef as mediaRefs in posts.

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 this tool is useful by noting that returned storageRef values can be used as mediaRefs in posts, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. There is no direct comparison to sibling tools like xplanner_list_posts or xplanner_register_media_asset.

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 openWorldHint=true, so the description does not need to restate safety. It adds the filter options (accountId, socialSetId, status) but these are also present in the schema. It does not disclose pagination behavior or response format beyond what the cursor schema description provides. Overall, it adds little beyond annotations and 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?

The description is a single, concise sentence that states the core action first and then lists filters. It is front-loaded and contains no unnecessary words. It earns a perfect score for efficiency.

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 list tool with 5 parameters and no output schema, the description could mention that it returns a paginated list and how to use the cursor. However, the cursor schema description already covers pagination mechanics. It does not mention default limit or sorting, but for a simple read operation with strong schema coverage, this is acceptable though not rich.

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 80%, so the baseline is 3. The description mentions the three filter parameters (accountId, socialSetId, status) but this is already covered in the schema. It adds no new meaning for limit or cursor, and the 'old/new' nuance for accountId/socialSetId is also in the schema. Thus it does not compensate beyond the baseline.

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

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

The description clearly states it lists the user's posts, a specific resource and action. It distinguishes from other list tools by naming 'posts' as the resource, and it mentions filter options. However, it does not explicitly differentiate from xplanner_get_post (single post retrieval) or other list tools, so it's clear but not maximally distinct.

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 no guidance on when to use this tool versus alternatives. It does not mention conditions, exclusions, or alternatives like xplanner_get_post or other list tools. An agent would have to infer usage from 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?

The readOnlyHint and openWorldHint annotations already cover safety, and the description adds useful behavioral context by disclosing that the result contains social sets with nested X, LinkedIn, and Threads accounts. No annotation contradiction 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?

The description is two short, purposeful sentences. It front-loads the action and resource, then immediately gives the practical usage context without any 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 usefully explains what is returned and how to use the returned IDs. It could be more explicit about behavior with and without workspaceId, though the schema already documents that optional filter.

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 only parameter, workspaceId, is already fully described in the schema with 100% coverage. The description adds no additional parameter-level meaning, so the 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 states a specific operation: listing 'Sosyal Setleri' and their embedded X, LinkedIn, and Threads accounts. This is clearly more specific than a generic list tool, but it does not explicitly differentiate itself from siblings like xplanner_list_accounts.

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 clearly says when to use it: when creating a post, choose socialSetId and publishTargets[].socialAccountId from these results. It does not mention when not to use it or point to an alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the behavioral constraint that only authorized workspaces are returned, which is valuable 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 short, purposeful sentences with no filler. The first sentence states the action, and the second provides usage context, making it well-structured 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 zero-parameter list tool, the description covers both what it does and when to use it. It does not describe the return format, but given the simplicity of the tool and the annotation support, this is a minor gap.

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

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

The tool has zero parameters and schema coverage is 100% (trivially). Per the rubric, a zero-parameter tool receives a baseline 4; there is no parameter information that the description would need to add.

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 ('lists authorized workspaces') and explicitly gives its purpose: selecting workspaceId in the new platform contract. This clearly distinguishes it from sibling list tools like xplanner_list_accounts or xplanner_list_folders.

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 a clear context for when to use the tool (selecting workspaceId in the new platform contract). It does not explicitly mention when not to use it or suggest alternatives, but the resource type is distinct enough 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 declare destructiveHint=true and readOnlyHint=false, so the description's 'publishes' aligns with those. The description adds the permission requirement ('posts:publish') and the immediacy ('anında' = instantly), which is useful. However, it doesn't disclose side effects like whether publishing is irreversible or what happens to the post's state.

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?

One concise sentence that states the action, target, and permission requirement. No wasted words, and the key information 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 single-parameter mutation tool with no output schema, the description is adequate but thin. It covers the action and permission but doesn't explain what a successful response looks like, whether the operation is reversible, or any preconditions (e.g., post must be in draft state). The annotations cover safety, but the description could add more behavioral context.

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 0%, so the description carries the burden for parameter meaning. The description mentions 'existing post' which implies the 'id' parameter refers to the post to publish, but it doesn't explicitly map 'id' to a post ID or explain the UUID format. Baseline 3 is appropriate because the description gives minimal context but doesn't fully compensate for the 0% schema coverage.

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

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

The description states a specific verb ('publishes') and resource ('existing post to the connected account'), which clearly distinguishes it from sibling tools like xplanner_create_post or xplanner_update_post. It doesn't explicitly name a sibling alternative, but the action 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?

The description implies when to use it: when an existing post should be published immediately. It does not explicitly state when not to use it or mention alternatives like scheduling or draft handling. The permission requirement ('posts:publish') gives some context but no explicit 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 already communicate mutation (readOnlyHint=false), non-destructiveness (destructiveHint=false), and idempotency (idempotentHint=true). The description adds contextual behavioral information: the asset becomes available for posts. It does not contradict the annotations, but it also does not explain side effects such as duplicate registration behavior or ownership constraints beyond what annotations imply.

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 efficient sentence with no filler; every clause earns its place by specifying the input condition and outcome. It is concise, though it sacrifices useful detail, which is handled in other dimensions.

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 12-parameter mutation tool with no parameter descriptions and no output schema, the one-sentence description is insufficient. It gives a general workflow hint but omits required-parameter semantics, return behavior, error conditions, and explicit relationship to create_media_upload_url or create_post.

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 0%, and the description names no parameters at all. With 12 parameters and 3 required ones, the description needed to compensate by explaining at least accountId, bucketId, and objectPath, but it provides no parameter-level 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 uses a specific verb ('kaydeder' / registers) with a clear resource ('XPlanner medya varlığı' / media asset) and adds a specific condition: the object was uploaded via a signed address. It also states the outcome ('gönderilerde kullanılabilir hale getirir'), which distinguishes it from siblings like create_media_upload_url, delete_media_asset, and list_media_assets.

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 'İmzalı adresle yüklenen nesneyi' implies this tool should be used after an upload performed with a signed address, and 'gönderilerde kullanılabilir hale getirir' implies it should be called before the asset is used in posts. However, it never explicitly names the workflow, prerequisites, or alternatives such as create_media_upload_url, so guidance remains 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 establish that the tool is mutating, non-destructive, and idempotent. The description adds the key behavioral guarantee that only provided fields are changed and that the folder must already exist, but it does not mention permissions, error behavior, or return value. Given annotation coverage, this is adequate but not rich.

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

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

Two short sentences with no filler; the core action and the partial-update caveat are front-loaded. Every phrase 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 simple partial update, the core behavior is covered, and annotations handle idempotency and destructiveness. But there is no output schema and the description says nothing about the response, error cases, or the role of idempotencyKey, leaving some uncertainty for an agent invoking the 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 schema already documents color, order, and isPinned; the description adds meaning by mapping name, color, order, and pinned status to the updatable fields. However, id and idempotencyKey receive no description-side help, and with 50% schema coverage the description does not fully compensate for the undocumented parameters.

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 operation ('updates the name, color, order, or pinned status') and identifies the resource as an existing folder. This clearly distinguishes it from create_folder, delete_folder, get_folder, list_folders, and the update_idea/update_post sibling tools by resource type.

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 clearly frames the tool for modifying an existing folder and explains partial-update semantics: only supplied fields change. It does not explicitly name alternatives or when not to use it, so it falls just short of a 5, but the usage context is unambiguous.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds meaningful behavioral context: it explicitly states that only the provided fields change (partial update semantics), which is valuable beyond the annotations. It does not contradict the annotations. It could have added more about error cases or permissions, but the partial-update disclosure is a solid addition.

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, compact sentence that front-loads the action and scope, then adds the key partial-update behavior. Every word earns its place; no filler or repetition of schema 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 partial-update tool with 7 parameters and no output schema, the description covers the core semantics well: what can be updated and that only provided fields change. It does not explain the mediaAssetIds parameter or idempotencyKey usage, but the schema partially covers those and the annotations carry the idempotency hint. The description is adequate for an agent to invoke the tool correctly for common cases.

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 57%, so the schema documents some parameters (title, content, folderId, isPinned) but leaves id, mediaAssetIds, and idempotencyKey without descriptions. The description adds high-level meaning by naming the updatable fields, but it does not explain mediaAssetIds or idempotencyKey semantics. The schema's per-parameter descriptions are already strong for the covered fields, so the description's marginal addition is modest but useful.

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 ('günceller' = updates) and resource ('mevcut bir fikir' = an existing idea), and lists the exact fields that can be changed: title, content, folder, and pinned status. This clearly distinguishes it from sibling tools like xplanner_create_idea or xplanner_delete_idea.

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 updating an existing idea and notes that only provided fields change, which is useful partial-update guidance. However, it does not explicitly state when to prefer this over alternatives, nor does it mention prerequisites like the idea needing to exist or the need for an idempotency key for retries.

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, destructiveHint=false, openWorldHint=true, and idempotentHint=true, so the description does not need to repeat those. The description adds that only provided fields change, which implies partial update semantics, but it does not disclose potential side effects, like whether updating scheduledAt triggers scheduling or if updating status to 'scheduled' validates other fields. At least it does not contradict annotations, so 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?

The description is one sentence, which is concise. It front-loads the key action ('updates an existing post') and adds the scoping constraint about only provided fields. No wasted words. However, given the tool's complexity, a slightly longer description could have earned a 5, but for a single sentence it is 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?

The tool has 9 parameters, no output schema, and only 11% schema coverage, so the description should compensate with more context. It lacks guidance on how parameters interact, such as the relationship between scheduledAt and status, or what happens when publishTargets is updated. The output is also not described, but with no output schema, the description could have mentioned return values. The description is minimally sufficient but leaves significant 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 only 11%, meaning the description must compensate for many parameters. The schema provides detailed types and enums for most parameters, but the description adds no explanation of what each parameter does. For instance, 'publishTargets' is described in the schema but not in the description. The description only mentions that provided fields change, which is generic. With low coverage and no extra parameter context, the description fails to add 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 verb ('günceller' – updates) and the resource ('mevcut bir gönderi' – existing post). It also notes that only provided fields change, which adds useful scoping. However, it does not explicitly distinguish from the sibling tools like xplanner_update_idea or xplanner_update_folder, but the resource is clearly different, so it earns a 4.

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: it is for updating an existing post, and it says only provided fields change, which hints at a partial update. However, it does not explicitly state when to use it versus alternatives (e.g., when to use xplanner_publish_post vs this) or when not to use it (e.g., if post is already published). No exclusions or prerequisites are mentioned, so this is a minimal viable score.

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