Posty

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

The description adds behavioral context beyond annotations by enumerating the specific state-changing actions (submit, approve, publish, retry) and noting that permissions and readiness checks apply. It does not contradict annotations (readOnlyHint=false, destructiveHint=true) and clarifies that actions like publish can be immediate or scheduled, providing useful operational detail.

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

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

The description is two concise sentences: the first lists all actions, the second gives permission/readiness context. No fluff, front-loaded with the most critical information about what the tool does.

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 (multiple action variants, nested objects), the description is minimal. It does not explain how to obtain the post id (path.id) or when to use each action's specific fields. However, the schema provides detailed parameter structure, and the description mentions permissions and readiness checks, making it adequate but not comprehensive for an agent unfamiliar with the workflow.

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 50% (workspaceId and idempotencyKey have descriptions; path and body do not). The description lists the allowed actions, which maps to the body.action parameter, but does not explain other parameters like path.id or the meaning of skipApproval, at, or visibility. The schema's oneOf structure is self-explanatory, but the description could compensate more 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 tool's purpose: performing workflow actions on a post (submit, approve, request changes, publish, retry). It uses a specific verb and resource, and the action list differentiates it from sibling CRUD tools like patch_posts_id or post_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 provides context about permissions and readiness checks ('The same permissions, review stages and readiness checks as the app apply'), but does not explicitly state when to use this tool versus alternatives or when not to use it. No sibling tool is mentioned as an alternative, leaving the agent to infer usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the basic safety profile. The description provides no additional behavioral context—e.g., whether deletion is permanent, cascades to associated data, affects other resources, or requires special permissions. The description does not contradict the annotations but adds negligible value 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?

While extremely short, the description is under-specified rather than concisely informative. The single line 'DELETE /v1/media/{id}' conveys the HTTP endpoint but omits essential context. It is not front-loaded with useful information because it contains no natural-language explanation.

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

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

With no description of the media resource, the effects of deletion, or any return/error behavior, the tool is not self-contained. Even with an output schema present, an agent cannot confidently use this tool without inferring meaning from the resource name and sibling context. The description fails to provide minimal domain grounding.

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 only 50% (workspaceId has a description, but path.id has none). The tool description adds no parameter-level explanation, so the meaning of the required 'id' field remains entirely undocumented. It does not compensate for the schema gaps.

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 is essentially a tautology: 'DELETE /v1/media/{id}' restates the tool's name and HTTP method without explaining what media is or what deletion entails. It does identify the resource (media) and the action (delete) but provides no domain-specific clarification, and it does not distinguish this from sibling delete tools like delete_posts_id or delete_post_content beyond the resource name.

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. It does not mention prerequisites, conditions (e.g., ownership, permissions beyond the workspace check), or scenarios where other delete tools are more appropriate. An agent has no context to decide between this and sibling delete operations.

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 only restates the DELETE endpoint and adds no behavioral context beyond the annotations. It does not disclose what deleting content means for the post, whether the operation is reversible, or what side effects occur; annotations already supply destructiveHint/idempotentHint.

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 terse and front-loaded, with no filler, but it is only a raw endpoint string rather than a structured explanation. It is concise without being a complete natural-language description.

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 operation with nested parameters, a one-line endpoint does not fully explain scope, prerequisites, or effects. The output schema exists, so return values need not be detailed, but the lack of any usage or consequence guidance leaves important gaps.

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

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

The path template gives meaning to the nested id and channelId parameters, which the schema otherwise leaves undocumented. workspaceId is described in the schema, so the description partially compensates for the 50% schema coverage, but does not explain the params in prose.

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 is an explicit DELETE endpoint path, so the verb and target resource (content of a post on a specific channel) are clear. It is distinct from siblings like delete_posts_id because the path includes /content/{channelId}, though it does not explain the operation in natural language.

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 choose this tool over delete_posts_id, delete_media_id, or patch_posts_id_content_channelId. The intended use is only implied by the HTTP method and path; no exclusions or alternatives are mentioned.

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

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

Annotations already state destructiveHint=true and idempotentHint=true, and the description adds no behavioral context beyond the literal DELETE method. It does not say whether the deletion is permanent, cascades to related content/comments/media, or what response is returned.

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 very short and free of fluff, but it is a bare endpoint template, not a structured explanation. It is economical enough yet sacrifices semantic detail for brevity.

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 tool with no auth/read hints and many sibling deletion endpoints, the description does not explain side effects, return shape, or how it differs from delete_post_content and delete_posts_postId_comments_id. An agent selecting among siblings would need more 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?

With 50% schema description coverage, the description should compensate for the undocumented path.id, but it only restates the URL template and adds no meaning about what id represents or how to supply it. workspaceId semantics are already documented in the input schema, so the description contributes little to parameter understanding.

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 endpoint string 'DELETE /v1/posts/{id}' clearly conveys a DELETE operation on a post resource, and the path shape distinguishes it from comment/content/media deletion siblings. It is a specific verb+resource, though it relies on the reader to infer that it deletes the post itself rather than a subresource.

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 indication of when to prefer this tool over delete_post_content or delete_posts_postId_comments_id, nor does it mention prerequisites or alternatives. It is only an HTTP method/path with no usage context.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no behavioral context beyond repeating the DELETE method, such as permanence, side effects, or authorization requirements. 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?

The description is a single short line with no wasted words, but it is under-specified rather than usefully concise. It essentially restates the tool name as an endpoint and does not add explanatory value.

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

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

For a destructive nested-resource deletion tool, the description omits usage context, parameter semantics, and behavioral details. The input schema and annotations partially compensate, but the description is not complete enough for safe and appropriate 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 only 50%, and only workspaceId is documented. The description merely repeats postId and id in the URI template without explaining their meaning, format, or relationship, so it does not compensate for the undocumented path 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 is the endpoint URI 'DELETE /v1/posts/{postId}/comments/{id}', which clearly identifies the verb and resource: deleting a comment on a post. It is precise and inferable, but it provides no prose and does not explicitly differentiate itself from sibling deletion 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?

There is no guidance about when to use this tool versus alternatives such as delete_posts_id or delete_media_id. The endpoint path implies the operation, but no context, prerequisites, or exclusions 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?

The description adds no behavioral context beyond the annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so there is no contradiction, but the description itself does not disclose filtering, pagination, or permission 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 short, but this is under-specification rather than effective conciseness. It states only an endpoint and omits the behavioral detail required for selecting and 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?

Even with useful annotations and an output schema, the description is too bare to be complete. It does not state that the endpoint lists channels, what filters are available, or how it relates to sibling tools.

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 50%, and the description provides no parameter meaning beyond the schema. The workspaceId is explained, but the query object and its fields such as ending_before and starting_after have no semantic explanation beyond their types and enums.

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 is just the HTTP endpoint "GET /v1/channels", which essentially restates the resource named by the tool. It does not explicitly say that it retrieves or lists channels, nor does it distinguish itself from sibling tools like get_channels_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?

No guidance is given about when to use this tool versus alternatives such as get_channels_id, get_posts, or list_workspaces. An agent would have to infer the intended scope from the tool name and endpoint.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds only the HTTP method and path, with no additional behavioral context such as behavior for nonexistent IDs, permission requirements beyond the schema note, or response characteristics. It provides no extra transparency beyond the annotations.

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

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

The description is extremely compact and contains no filler or repetition. It conveys the endpoint and method efficiently. However, it is so terse that it relies on the tool name for meaning, preventing a perfect score.

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 do not need to be explained. Still, the description lacks plain-language purpose, usage context, and sibling differentiation, which are important for an agent selecting among many similar tools. The annotations cover safety, but the overall description is not complete enough for confident 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?

The schema describes workspaceId with permission context, and the route template makes clear that path.id is the channel identifier. The description itself only contributes the '{id}' placeholder meaning, while workspaceId semantics come from the schema. This partially compensates for the 50% schema description 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 the HTTP verb and resource path: 'GET /v1/channels/{id}'. This clearly identifies the operation as retrieving a single channel by ID, and the '{id}' path element distinguishes it from the sibling list tool get_channels. However, it relies on the path/name rather than a plain-language statement of the outcome.

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 about when to use this tool versus get_channels or other siblings. The description provides no context, exclusions, or alternative recommendations. An agent must infer from the tool name and path that this is for fetching a specific channel rather than listing channels.

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 disclose readOnlyHint=true and idempotentHint=true, but the description adds no behavioral context beyond the endpoint string. It does not mention pagination behavior, scoping, auth implications, or how results are ordered.

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 short and front-loaded, so there is no redundancy. However, it is under-specified rather than usefully concise, providing only an endpoint string with no explanatory substance.

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 endpoint with nested query parameters and several sibling tools, the description omits what the tool returns, how to filter, and when to choose it. The output schema helps, but the description does not orient an agent enough to call 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?

The description adds no meaning to either parameter. The schema documents workspaceId, but the nested query object's properties (limit, status, contentType, cursors) are left without explanatory context in 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 is just 'GET /v1/media', which restates the tool name and endpoint without stating what the tool does in natural language. It implies listing media but does not explicitly differentiate from get_media_id or clarify the resource 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?

There is no guidance on when to use this tool versus alternatives like get_media_id, post_media, or delete_media_id. An agent is left to infer the intended use case from the schema and sibling names 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the redundant GET verb; it does not mention response format, error behavior, permissions, or side effects.

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 maximally short but under-specified; a single endpoint string is concise but not a usable definition. It lacks a front-loaded human-readable summary and omits information an agent needs to understand the tool's role.

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?

Even though an output schema and annotations exist, the missing purpose and usage context make the tool incomplete for an agent deciding between get_media, get_media_id, and related media endpoints. The description does not explain what the id identifies, what 'media' means, or when this tool should be called.

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 endpoint template identifies {id} as a path parameter, but the schema already defines path.id and workspaceId. With schema description coverage at only 50%, the description should clarify the meaning of 'id' and the resource being fetched, but it does not. workspaceId's meaning comes from the schema, not 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 is only the raw endpoint 'GET /v1/media/{id}', which essentially restates the tool name and gives no human-readable explanation of what 'media' is or what the returned object represents. It conveys a read action by id but does not clearly distinguish itself from siblings like get_media or get_media_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?

No usage guidance is provided. The description only shows an HTTP route and gives no indication when to prefer this tool over get_media, post_media, or other sibling tools, nor does it mention prerequisites 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?

The endpoint matches the annotations: readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The GET verb and '/history' path are consistent with a read operation, so there is no contradiction. However, the description adds no behavioral context beyond the annotations and the endpoint itself, such as pagination, ordering, or scope of the history data.

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 short and puts the HTTP method and resource path up front, so it is not verbose. But it is under-specified rather than appropriately informative; a single endpoint string is concise but leaves key semantics unexplained.

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 two required parameters, a nested path object, many sibling tools, and an output schema, the description should at least clarify what 'history' contains and how this call differs from related GET endpoints. It provides none of that, so an agent must guess or inspect other sources to use 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?

Schema coverage is 50%: workspaceId has a meaningful description, but path.id is described only by type and minLength. The endpoint string implies that id is the post ID, but neither the description nor the schema states this explicitly. The description does not compensate for the undocumented nested path 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 is only the endpoint string 'GET /v1/posts/{id}/history', which conveys the action (get) and a 'history' subresource of a post. However, it never explains what kind of history is returned (edit history, activity log, revisions, etc.), and it does not explicitly differentiate itself from sibling tools like get_posts_id or get_posts_postId_comments.

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

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

There is no when-to-use guidance, no mention of alternatives, and no conditions or exclusions. Sibling tools such as get_posts_id and get_posts_postId_comments are not referenced, so the agent receives no help deciding when this tool is the right one.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral detail beyond the HTTP method and path; it does not mention pagination, filtering behavior, ordering, or response characteristics.

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 short and front-loaded, but this is under-specification rather than effective conciseness. A single endpoint string does not meaningfully describe behavior, so the sentence does not earn its place as a useful tool description.

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

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

Given a nested query object with filters, pagination parameters, and a required workspaceId, this description is far from complete. The output schema and annotations help, but the description leaves major selection and invocation questions unanswered, especially around filtering and list versus single-post 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?

The schema provides a description only for workspaceId, and the query object's subproperties are self-explanatory only by name. The description adds zero parameter meaning, does not explain the required workspace context, and does not compensate for the 50% schema description 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 is literally 'GET /v1/posts', which mostly restates the tool name and endpoint without explaining what the tool does semantically. It does not state that it retrieves a list of posts, what scope it covers, or how it differs from get_posts_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?

There is no guidance about when to use this tool versus siblings like get_posts_id, get_post_history, or get_channels. The description gives no context about whether this is the collection-level list endpoint or a filtered search, so an agent has to guess.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the HTTP method, but it does not contradict the annotations. With annotations carrying the burden, a 3 is appropriate.

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

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

The description is extremely short, but it is under-specified rather than concise. It provides no human-readable explanation of the operation, response, or context, so the single line does not earn its place as a useful tool description.

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?

Although an output schema exists and annotations cover safety, the description is incomplete for an agent trying to select this tool. It does not clarify what resource is returned, how it differs from get_posts, or what the id path parameter refers to. The workspaceId description helps, but the core purpose is missing.

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

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

Schema description coverage is 50%: workspaceId has a helpful description, but path.id has only a type. The description adds no parameter meaning beyond the schema. Baseline 3 is appropriate because the schema partially documents parameters and the endpoint pattern implies the id is the post 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 is just the HTTP endpoint 'GET /v1/posts/{id}', which restates the tool name and gives no verb beyond the HTTP method. It does not state what a post is, what the response contains, or how it differs from siblings like get_posts or get_post_history.

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 about when to use this tool versus alternatives. The sibling list includes get_posts, get_post_history, and get_posts_postId_comments, but the description does not mention any selection criteria 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 already declare readOnlyHint=true and idempotentHint=true, but the description adds no behavioral context. It does not mention pagination, return format, permissions, or any operational characteristics. With annotations present, the description fails to contribute any additional transparency.

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 line, but it is under-specification rather than conciseness. It does not earn its place because it adds no information beyond the tool name. It lacks front-loaded content and is essentially empty of 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?

With a low schema coverage and no description text, the tool is completely under-specified. An agent has no idea what the endpoint returns, what the parameters do, or how to construct a valid request. The output schema exists but the description does not help in understanding it. This is grossly inadequate for a tool with three parameters and nested objects.

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 33% (only workspaceId has a description). The path.postId and query parameters (limit, ending_before, starting_after) are undocumented in the schema, and the description provides no explanation of their meaning or usage. The description adds zero value to parameter semantics.

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 is just the HTTP method and path, which is essentially a restatement of the tool name. It does not state what the tool does beyond the endpoint. No verb or resource explanation is provided, so an agent cannot infer the tool's purpose from the description alone.

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

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

There is no guidance on when to use this tool versus alternatives like get_posts or get_posts_id. The description offers no context for selection, no exclusions, and no mention of related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no behavioral context such as return format, pagination, or rate limits. With annotations present, the bar is lower, but the description still contributes nothing beyond the endpoint path.

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 – a single string with the HTTP method and path. It is not verbose, but it is also minimal to the point of being under-specified. For a simple list endpoint, this brevity is acceptable, though a short sentence describing the action would be more structured.

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 an output schema exists and annotations cover safety, the description still lacks essential context such as what the response contains, whether pagination is involved, or how this relates to sibling workspace tools (none exist). It is barely complete enough for an agent to invoke correctly, relying almost entirely on the tool name and 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?

The tool has zero parameters and the schema is empty with 100% coverage. Since there are no parameters to document, the description does not need to add parameter semantics. Baseline for 0 params is 4, and the description does not detract from this.

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 'GET /v1/workspaces' conveys the HTTP method and resource but does not explicitly state it lists workspaces. It is clearer than a tautology but lacks a descriptive verb beyond the implied GET. It does not differentiate from sibling tools beyond the resource name, though no other tool targets workspaces.

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 vs. alternatives. No mention of filtering, pagination, or context that would help an agent decide between this and sibling list tools like get_channels or get_posts. The description provides zero usage direction.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is known. However, the description adds zero behavioral context on top of that—it does not explain partial-update semantics, what happens when scheduledAt is set to null versus omitted, or whether status changes trigger side effects. No contradiction with annotations, but no added value either.

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 short, but this is under-specification, not conciseness. A bare HTTP method and path string carries no decision-relevant information beyond what the tool name already encodes, so nothing in the description '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 explained, but this is a complex, destructive mutation tool with nested body semantics and an eight-state workflow enum. The description leaves the agent to infer everything from the schema, including the meaning of the id, state-transition rules, and how this endpoint relates to the several nearby patch/put/delete siblings.

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 33% (only workspaceId is described), and the description text contributes no parameter meaning at all. The body schema's enums (status workflow states, approvalMode) carry real semantic weight, but the description fails to explain their interplay—e.g., whether scheduledAt requires status='scheduled' or which status transitions are valid.

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 'PATCH /v1/posts/{id}' merely restates the tool name in HTTP endpoint form; it adds no semantic content about what the tool does. It does not state what fields are updated, what resource lifecycle it touches, or how it differs from siblings like patch_posts_id_content_channelId or put_posts_id_content_channelId_media.

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. Closely related siblings exist (post_posts, put_posts_id_content_channelId_media, patch_posts_id_content_channelId), yet the description offers no conditions, exclusions, or routing hints to help an agent choose correctly.

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

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

Annotations already hint that this is destructive and not read-only, but the description adds no behavioral context beyond the PATCH method. It does not say whether existing content is overwritten, whether null body clears content, or what side effects occur; however, 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?

The description is very short and front-loaded, but it is under-specified and largely duplicates the tool name. It contains no information that justifies its presence beyond the endpoint string.

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 having an output schema and structural parameter details, the description is incomplete for a destructive PATCH operation with a nested body. An agent lacks enough behavioral and parameter context to confidently call this 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 33%, with only workspaceId described. The description merely echoes {id} and {channelId} from the path and gives no meaning for the body.content or metadata fields, leaving important semantics undocumented.

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 is just the endpoint template 'PATCH /v1/posts/{id}/content/{channelId}', which essentially restates the tool name. It does not state what patching content does, whether it replaces, creates, or deletes content, or how it differs from siblings like patch_posts_id or put_posts_id_content_channelId_media.

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 usage guidance is provided. The description gives no context for when to use this tool instead of related tools such as patch_posts_id, put_posts_id_content_channelId_media, or delete_post_content.

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 are all false (non-informative), leaving the description as the sole source of behavioral disclosure. The description gives no indication of what gets created, idempotency semantics, content size limits, auth/permission requirements, or response behavior. It adds no behavioral context beyond the raw endpoint path.

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 token with no wasted words, but this is gross under-specification rather than crafted conciseness. There is no information that earns its place because there is effectively no information at all.

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 a nested body object, three parameters, an output schema, and many closely related siblings, this description is radically inadequate. An agent cannot determine what the tool does, when to call it, or what it returns. Nothing needed for correct invocation is provided.

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 67%, with workspaceId and idempotencyKey documented in-schema while the body object — the core payload — is not described, and neither are its properties (title, contentType, sizeBytes). The description 'POST /v1/media' adds nothing about parameters or their meaning, failing to compensate for the undocumented body.

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 'POST /v1/media' merely restates the endpoint as the HTTP verb plus resource path, essentially echoing the tool name. It provides no semantic meaning about what 'media' is, whether this creates or uploads content, or how it differs from sibling tools like post_media_id_complete and post_posts. This is close to a tautology.

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

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

There is no guidance on when to use this tool versus alternatives such as put_posts_id_content_channelId_media or post_media_id_complete. No context about prerequisites, sequencing, or exclusions is provided; the description carries zero usage direction.

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

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

Annotations provide no safety hints beyond all-false values, so the description carries the full burden for behavioral disclosure. It says nothing about side effects, prerequisites, state transitions, or idempotency behavior. The word 'complete' implies some state change, but it is left unnamed.

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 terse line, but it is under-specification rather than conciseness. It only echoes the endpoint and provides no added information that 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 4-parameter mutation-style operation with a nested body and an output schema, this description is far too thin. An agent cannot determine when to call it, what the request body means, or what effect it has on the referenced media.

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?

workspaceId and idempotencyKey have schema descriptions, but body properties (etag, width, height, duration) and path.id do not. The description adds no parameter meaning and does not clarify what these fields represent or how they are used in the completion flow.

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 is only the HTTP method and URL, restating the tool name. It identifies the resource but not what 'complete' means—no verb with semantic content. It fails to distinguish from post_media or other siblings beyond path.

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 statement of when to use this tool, what scenarios call for it, or alternatives. The endpoint path hints at finishing a media upload, but that is never stated and no comparison is made to post_media, delete_media_id, or get_media.

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, not idempotent, and not destructive. The description adds no behavioral context beyond the endpoint, such as permission requirements, workspace-scoped side effects, approval flow behavior, or retry semantics.

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 short, but this is under-specification rather than effective conciseness. It provides only the endpoint string and no explanatory content, so it does not earn its place as a useful tool description.

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

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

Given a nested body schema, approval options, workspace permissions, and many sibling post-related tools, a one-line endpoint is not complete enough. The schema and annotations carry the load, but the description fails to explain what creating a post entails or how this tool relates to the other post and content tools.

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 67%, and the description itself adds no parameter meaning. The required body object lacks a description, and while property names like content, scheduledAt, and approvalMode are reasonably self-explanatory, the description does nothing to clarify payload semantics or parameter relationships.

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 only 'POST /v1/posts', which conveys a create-post endpoint through REST convention but never says in plain language that it creates new posts. It is not a tautology, but it relies on the agent inferring meaning from the HTTP method and path rather than an explicit purpose statement.

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 about when to use this tool versus siblings such as patch_posts_id, delete_posts_id, or post_posts_postId_comments. The description gives no selection criteria, prerequisites, or alternative routing information.

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=false, and openWorldHint=false. The description adds zero behavioral information—no mention of side effects, required permissions, rate limits, or response behavior. For a POST action that creates a resource, the lack of disclosure about what gets created or any mutation semantics is a significant gap.

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 brief—a single endpoint string. This is under-specification rather than concise writing. It lacks a proper sentence or bullet structure and does not front-load any useful context. The description could be a few words longer to be genuinely helpful.

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 (nested objects, 4 parameters, an output schema), the description is completely inadequate. It does not explain what the response contains, how to construct the request body, or any edge cases. An agent would have to rely entirely on the schema and other signals, which are also incomplete.

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 50% (only workspaceId and idempotencyKey have descriptions). The description itself does not explain any parameters, such as the required body object (which likely contains the comment text) or the path postId. It fails to compensate for the undocumented parameters and adds no meaning beyond the schema.

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

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

The description is only the raw HTTP endpoint 'POST /v1/posts/{postId}/comments', which states a verb and resource but does not explicitly say 'create a comment on a post'. It adds minimal clarity beyond the tool name and fails to distinguish itself from siblings like get_posts_postId_comments or delete_posts_postId_comments_id. This is closer to a tautology than a clear purpose statement.

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 tool versus the sibling tools. It does not mention alternatives, prerequisites, or conditions that would select this tool. There is no context about creating vs. listing vs. deleting comments.

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 nothing about side effects, permissions, or what happens to existing media. Annotations indicate destructiveHint=true and idempotentHint=true, but the description doesn't disclose any behavioral nuances beyond the raw endpoint. It is silent on what gets changed or replaced.

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 terse (a single line), but it's under-specification rather than effective conciseness. It lacks any explanatory content, so it doesn't earn its place; it's just a stub.

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 nested objects, an output schema, and a destructive hint, the description is grossly inadequate. An agent cannot determine what the operation does, what the parameters mean, or what the response looks like. It is essentially non-existent.

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 33%, and the description provides no parameter explanations. Only workspaceId has a description in the schema; body.mediaIds and path.id/channelId are undocumented. The description does not compensate for this gap at all.

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 is just the HTTP method and endpoint path (PUT /v1/posts/{id}/content/{channelId}/media). It identifies the verb and resource but does not explain what the operation does (e.g., attach media to a post's content). It's essentially a restatement of the tool name, which already contains 'put_posts_id_content_channelId_media'. There is no behavioral description.

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 on when to use this tool versus siblings like post_media, delete_media_id, or patch_posts_id_content_channelId. The description provides no context about selection criteria, prerequisites, or alternatives.

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