Postel

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds genuinely useful behavior: the operation is non-publishing, non-scheduling, and non-idempotent ('Each call creates a separate draft'), which warns against accidental duplicate drafts. It omits any note on required auth or what the created draft returns.

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

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

Three short sentences, zero filler, and the core purpose is front-loaded before the constraints. Every sentence earns its place by adding either scope or behavioral guidance.

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

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

For a simple two-parameter create with no output schema, the description covers purpose, exclusions, and the duplicate-draft behavior. It could be slightly more complete by indicating what the call returns (e.g., a draft id), but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters (content, status with its enum and default) are fully documented in the schema. The description's 'Save text' loosely maps to content but adds no format, length, or status semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Save text as a new draft') with the target system named, and immediately scopes it against the obvious siblings by saying it does not publish or schedule. An agent can distinguish it from publish-post, schedule-post, and update-post without opening any schema.

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

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

The description gives clear negative guidance ('Does not publish or schedule'), which effectively routes the agent toward publish-post/schedule-post for those needs. It stops short of naming those alternatives explicitly, so it is strong context rather than a full when/when-not/alternative mapping.

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 safety is covered. The description adds genuinely new context beyond the annotations: that a scheduled post's delivery is cancelled first, which is important consequence information for an irreversible action.

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

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

Two short sentences with zero waste; the core action is front-loaded ahead of the secondary side-effect detail. Nothing is padded or redundant.

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

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

For a single-parameter destructive tool with full schema coverage and no output schema, the description covers the action and its key side effect. It is nearly complete, missing only explicit routing toward alternatives and any confirmation/irreversibility caveat.

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?

There is a single parameter with 100% schema description coverage, so the schema fully documents postId. The description adds nothing about the identifier format or source, which is acceptable given the high coverage 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?

States a specific verb and resource (delete a post), and adds the meaningful scope note that scheduled deliveries are cancelled first. It does not explicitly contrast with siblings like update-post or get-post, but the namespace makes the intent 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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The scheduled-post note is a behavioral detail, not usage routing, so the agent gets no help deciding when deletion is the right action.

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, destructiveHint=false, and openWorldHint=true, so the write/side-effect profile is partly covered. The description adds the quota requirement, which is genuinely useful behavioral context. But it omits the most consequential fact for an agent: whether the generated post is saved/returned only, or also affects the account, which matters enormously next to publish-post and create-post siblings. It also doesn't mention the external AI call implied by openWorldHint.

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, front-loaded with the purpose, then the precondition, then the return. No filler, though the opener slightly restates the title 'Generate post with AI'.

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 four parameters and no output schema, the description is serviceable but thin: it says 'Returns the generated post' without saying whether that post is persisted, and with siblings named create-post, refine-post, and publish-post, the lifecycle position of the generated artifact is exactly what an agent needs. The quota note partially compensates.

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

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

Schema description coverage is 100%, and the parameter descriptions already explain prompt, isThread (X-only vs LinkedIn behavior), platform defaults, and profileId defaults. The description adds nothing beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource plus the generation mechanism ('Generate a new post using AI based on a prompt'), which is clearer than a bare tautology. However, it never distinguishes itself from the sibling create-post or refine-post, so an agent cannot tell from the description alone whether generating is the same as creating or whether the result is persisted.

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

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

It gives one real precondition — 'Requires usage quota' — which tells the agent a metered action is involved. But there is no when-to-use guidance relative to create-post, refine-post, or publish-post, and no indication of when-not to call it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds that the returned sources are background information used for AI post generation, but it does not disclose return format, pagination, or authorization requirements beyond what the annotations provide.

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

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

The description is two concise sentences with no wasted words. It front-loads the core action (getting sources for a brand) before adding the purpose (informing AI post generation).

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

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

For a simple, read-only, single-parameter tool, the description plus annotations are nearly sufficient. The main gap is that no output schema exists and the description does not describe the shape of the returned sources, though this is a minor omission given the tool's simplicity.

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

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

The single parameter brandId is fully documented in the input schema with a clear description. The tool description reiterates that sources are for a specific brand, but adds no syntax, format, or constraint details beyond the schema. With 100% schema coverage, 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 verb and resource: getting background information sources for a specific brand. It is clear what the tool returns and for whom, but it does not explicitly contrast itself with sibling tools like list-brands or get-x-profiles.

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 implied usage by saying these sources are used to inform AI post generation, which suggests when an agent might call it. However, it does not state when to use this tool versus alternatives, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only 'full details,' which hints at return richness but discloses no behavior beyond the annotations (no error/not-found behavior, no pagination or caching notes).

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

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

A single front-loaded sentence with zero waste. The verb, resource, and lookup key all appear immediately.

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

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

For a simple one-parameter read tool with full annotation coverage and no output schema, this is nearly sufficient. The only gap is that 'full details' is not unpacked, but the agent needs little more 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?

Schema description coverage is 100% for the single postId parameter, so the schema already documents it fully. The description adds no format, source, or constraint information beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ('Get a single post') and adds scope ('by ID with full details'). It is distinguishable from create-post/delete-post/list-posts, but it doesn't explicitly contrast itself with other retrieval siblings like list-posts or search-viral-tweets.

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

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

No when-to-use or when-not-to-use guidance. The description implies retrieval by ID, but never states prerequisites (e.g., that the ID must come from list-posts) or when a sibling should be used instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by characterizing the payload as a template and specifying that it exposes configured time slots for each day of the week, which is not derivable from the structured fields (no output schema exists).

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

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

Two tight sentences with zero filler; the resource and scope come first and the return content follows. Every clause earns its place.

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

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

For a zero-parameter read with annotations covering the safety profile, the description supplies enough to call the tool correctly. It stops short of stating whether the template is org-wide default versus per-profile, a minor but real gap given siblings like get-x-profiles exist.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description is not required to compensate. Baseline of 4 applies for a parameterless read.

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

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

States a specific verb and resource (get the posting schedule template) plus the scope (current organization), and previews the return shape (time slots per day of week). It is clearly distinguishable from schedule-post, though it never explicitly names or contrasts a sibling.

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 and no mention of alternatives such as schedule-post or update-post. The only contextual cue is that the schedule is scoped to the current organization, which an agent could infer anyway.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds one useful piece of context the schema cannot convey: the data is organization-scoped (no parameters), but it says nothing about freshness, quota-exceeded behavior, or plan-tier 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?

A single sentence with zero filler, front-loading the verb and the two things returned. Nothing could be cut without losing information.

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

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

With no output schema, the description carries the return-value burden and does partially discharge it by naming 'usage statistics' and 'plan limits'. For a zero-parameter read-only tool this is nearly sufficient, though it doesn't sketch the shape of either.

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?

There are zero parameters, so per the rubric the baseline is 4. The description reinforces this by naming the implicit scope ('for the organization'), which tells the agent no filtering arguments are expected.

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

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

States a specific verb and resource ('Get the current usage statistics and plan limits') and scopes it to 'the organization'. It is clearly distinct from the post/brand-centric siblings, though the description doesn't 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 word 'current' implies on-demand retrieval of live usage, but the description never states when an agent should call this (e.g., before scheduling posts to check quota) or names any alternative. With no close sibling offering usage data, the ambiguity is low, so this is implied usage rather than absent guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful domain context (profiles define brand voice for AI post generation) but says nothing about scope of return, whether profiles can be missing, or auth requirements.

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

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

Two sentences, front-loaded with the action and resource, followed by a single clarifying sentence about purpose. No filler.

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

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

For a parameterless read tool with no output schema, the description is nearly sufficient: it names the resource and its purpose. It could note that the return contains both profiles or what happens if none exist, but nothing critical 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 tool takes zero parameters, so per the baseline there is nothing for the description to compensate for. Schema coverage is moot and the description correctly does not invent 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?

States a specific verb ('Get') and resource ('X and LinkedIn voice profiles') scoped to the current organization, which is unambiguous. No sibling covers voice profiles, so differentiation isn't strictly needed, but it isn't explicitly established either.

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

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

The description explains what the profiles are but never says when to call this tool, what precedes it, or how it relates to siblings like generate-post or refine-post that presumably consume the brand voice. The usage context is only implied.

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

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

Annotations already declare this as a safe, read-only, non-destructive, non-open-world operation, so the behavioral burden is light. The description adds the organization-scoping constraint and the role of brands, but says nothing about return format, ordering, or what an empty result means.

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, front-loaded with the action and scope. Every clause contributes information.

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

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

For a parameterless, read-only list tool with no output schema, the description covers the essential scope and meaning of the resource. Only minor gaps remain, such as what a brand record contains beyond 'background information'.

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

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

The tool takes no parameters, so the schema-based baseline of 4 applies; there is no parameter semantics for the description to clarify.

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

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

States a specific verb and resource (list brands) and clarifies the domain term by equating brands with topics and scoping them to the current organization. It does not, however, differentiate itself from the sibling get-brand-sources, which an agent might confuse with this tool.

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

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

The description notes that brands hold background information used for AI post generation, which hints at context, but it gives no explicit when-to-use guidance, no preconditions, and no routing against alternatives like get-brand-sources or list-posts.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the organization-scoping behavior, which is useful multi-tenancy context, but says nothing about result ordering, pagination mechanics, or volume limits beyond the word 'pagination'.

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 resource and scope, with zero filler or redundant restatement of the title.

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

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

For a simple two-parameter read tool with annotations covering safety, the description is adequate but thin. With no output schema present, an agent gets no signal about the returned post shape or pagination continuation behavior, which the description could have supplied.

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

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

Schema description coverage is 100%, so both parameters (limit with max/default, status enum) are fully documented in the schema. The description only restates that status filtering and pagination exist, adding no syntax or default detail beyond the schema. Baseline 3 is correct.

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

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

States a specific verb and resource ('List posts') plus the scope constraint ('for the current organization'), which distinguishes it from get-post's single-item retrieval. It does not explicitly differentiate itself from the other listing tool (list-brands), but the resource 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?

'Supports filtering by status and pagination' hints at how to narrow results, and the resource scope implies the use case. However, there is no explicit guidance on when to use this versus get-post or a search-style sibling, and no stated 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, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds non-derivable context: the plan entitlement gate and the idempotence-like precondition that published posts cannot be published again. It stops short of saying what happens on partial failure or platform-side rate limits.

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, front-loaded with the action, then the entitlement constraint, then the precondition. No filler, no restating the tool name.

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

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

For a one-parameter destructive mutation with annotations covering safety, the description supplies the two things an agent most needs: the plan requirement and the cannot-republish rule. With no output schema it need not describe returns, though success/failure semantics are left implicit.

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

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

There is a single parameter (postId) and schema coverage is 100%, so the schema already documents it fully. The description adds nothing about the ID's format or origin (e.g. from list-posts/get-post), so the baseline 3 applies.

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

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

States a precise verb (publish), resource (a Postel draft), and scope (immediately, to the platform stored on the post). The word 'immediately' cleanly separates it from schedule-post, and the draft framing separates it from create-post and update-post without needing to name 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?

Gives real preconditions: a plan that includes publishing is required, and an already-published post cannot be re-published. It does not explicitly name schedule-post as the alternative for deferred publishing, which is the obvious sibling an agent might confuse this with.

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

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

Annotations already declare non-destructive, non-read-only and open-world behavior; the description usefully adds that no changes are persisted and that a usage quota is consumed, which annotations cannot express. It stops short of describing the returned suggestion payload, which would matter for a preview tool.

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

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

Two short sentences, front-loaded with the action and immediately followed by the two constraints an agent must know (no persistence, quota cost). No filler.

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

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

For a two-parameter tool with full schema coverage and clear annotations, the description covers the key behavioral facts. The one gap is that no output schema exists and the description doesn't state what the suggestion response looks like or how large it is.

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

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

Schema coverage is 100%, including a good example for 'instructions', so the schema already carries the semantic load. The description only gestures at 'instructions' generically and adds no format, length, or content constraints beyond the schema's maxLength.

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

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

States a specific verb (suggest/refine), the resource (an existing post), and the mechanism (AI + specific instructions) in one sentence. The phrase 'Does not save changes' separates it from update-post without the agent needing to open either schema.

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

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

The 'does not save changes' clause implies usage context (preview before calling update-post), but no sibling is named and no explicit when/when-not is given. 'Requires usage quota' is a prerequisite hint, not routing guidance. Usage is inferable rather than 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true; the description adds real value beyond them by disclosing the plan/entitlement prerequisite and the timestamp validity constraint. It still omits what happens if the post is already scheduled or published (overwrite vs. error) and any rate limits.

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

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

Three tight sentences that front-load the action and follow with prerequisites and the timestamp constraint; nearly every clause carries information. Slightly redundant with the schema's own note about the timestamp being in the future.

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 two-parameter mutating tool with no output schema, the description covers purpose, entitlement requirement, and the key input constraint. Missing only edge-case behavior (rescheduling/idempotency, error conditions), which the annotations' destructive flag makes somewhat important.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description restates the future-UTC requirement already present in scheduledDateTime's schema description, adding no syntax or format detail beyond it.

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

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

States a specific verb (schedule) and resource (a Postel draft) and clarifies the target platform is derived from the post. It is distinguishable from publish-post (immediate) and create-post, though it does not explicitly name the sibling it differs from.

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

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

Gives a clear precondition (a plan that includes scheduling) and a hard constraint (scheduledDateTime must be a future UTC ISO-8601 timestamp), which tells the agent when this call will succeed. It stops short of stating exclusions, e.g., how it relates to publish-post or whether an already-scheduled post should be updated instead.

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

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

Annotations already indicate read-only, closed-world, non-destructive behavior, but the description adds meaningful context beyond them: no login required, indexed rather than live data, possible metric staleness, and third-party post text in results. This gives the agent a clear behavioral and data-quality picture.

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

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

The description is three tightly written sentences, front-loaded with the core purpose. Every clause adds useful scope or data-quality context without repetition.

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

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

With no output schema, the description compensates by describing result content: source links, stored engagement metrics, and third-party post text. It also covers key limitations around indexed data, staleness, and authentication, making it complete enough for correct invocation.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description reinforces the topic and high-performing concepts but adds no syntax, default, or format details beyond the schema.

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

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

The description uses a specific verb and resource: 'Find high-performing public X posts in Postel's index by topic.' It clearly distinguishes the indexed search scope from live X and complete archives, but does not explicitly differentiate from siblings like list-posts or get-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 by 'by topic' and the high-performing focus, and the description gives useful scope exclusions ('not live X or a complete archive'). However, it does not state when to choose this tool over sibling tools such as list-posts or get-post.

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 and destructiveHint=true, so the mutation/destructive nature is covered. The description usefully adds the draft-only state restriction, but says nothing about partial updates, permission requirements, or what happens to unspecified fields when only one of content/status is supplied.

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, zero filler, and the core purpose is front-loaded ahead of the scope constraint. Every clause earns its place.

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

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

For a 3-parameter mutation tool with annotations that already convey the destructive profile and no output schema, the description covers purpose and the key state restriction. It could say more about partial-update semantics, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100%, so postId, status, and content are fully documented in the schema with an enum and maxLength. The description merely echoes the updatable fields ('content or status') without adding format, constraints, or interaction details, so the schema does the heavy lifting.

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

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

The description states a clear verb and resource ('Update the content or status of a Postel draft') and scopes the operation to drafts, which implicitly separates it from publish-post/schedule-post. It stops short of naming a specific sibling as the alternative, so it lands just below the top tier.

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 when-not guidance ('Scheduled and published posts cannot be edited'), which tells the agent when this tool will fail. It does not name alternative tools for those cases (e.g., delete-post, get-post), so it is clear-but-incomplete rather than a full routing statement.

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