Notipo

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

The description discloses that the tool 'Creates a Notion page and triggers sync to WordPress,' which is a significant side effect beyond what the annotations (`readOnlyHint: false`) convey. This adds valuable context about the multi-system impact of the operation, going beyond the minimum that annotations alone would suggest.

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 exceptionally tight—four short sentences that front-load the core action and pack in side effects (Notion + WordPress), format (markdown), and publish semantics (draft vs. immediate). Every sentence earns its place with zero fluff.

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

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

For an 8-parameter tool with a well-populated schema and annotations, the description covers all non-obvious aspects: the Notion/WordPress workflow, markdown requirement, and publish toggle behavior. It doesn't discuss tags, slug, or category, but these are self-explanatory and fully described in the schema, making the description sufficiently complete.

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

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

With 100% schema coverage, the schema already documents all 8 parameters clearly. The description adds marginal value by specifying 'The body should be markdown'—a format hint not present in the schema—and rephrasing the `publish` behavior. This pushes it slightly above the baseline of 3.

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

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

The description opens with a specific verb+resource ('Create a new blog post') and immediately adds distinguishing context about creating a Notion page and syncing to WordPress. While the core purpose is crystal clear, it doesn't explicitly differentiate from sibling tools like `direct_publish` or `publish_post`, so it earns a 4 rather than a 5.

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

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

The description implies usage context—creating blog posts with markdown content—and explains the two modes via the `publish` flag ('Set publish=true to publish immediately, or leave false to create a draft'). However, it never explicitly addresses when to use this tool versus the sibling `direct_publish` for immediate publishing, which feels like a missed opportunity given the overlapping functionality.

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

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

Annotations already mark destructiveHint=true, but the description adds valuable context: it deletes from both Notipo and WordPress, resets the Notion page status, and explicitly states 'This cannot be undone.' These side effects go beyond the annotation.

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

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

The description is a single, front-loaded sentence followed by a short warning. It is concise and every word adds value, with no unnecessary 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 destructive tool, the description covers key behavioral aspects: what is deleted, from which systems, the Notion status reset, and irreversibility. It doesn't mention prerequisites or error handling, but the existence of an output schema likely covers return values.

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

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

The input schema fully documents the only parameter postId with a clear description. The tool description adds no additional parameter-specific meaning, so with 100% schema coverage, the baseline score of 3 is warranted.

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

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

The description clearly specifies the verb 'Delete' and the resource 'a post' across multiple systems (Notipo, WordPress, Notion). This distinguishes it from sibling tools like update_post or publish_post, making its purpose unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. However, the action 'Delete' and the irreversibility warning imply it should be used when permanent removal is intended, offering implied usage 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 provide readOnlyHint=false and destructiveHint=false, so the description adds value by detailing side effects: image uploads, Gutenberg conversion, featured image generation, and SEO metadata handling. It also clarifies draft vs. live behavior. Slightly more could be said about reversibility or permission requirements, but the core behavior is disclosed.

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

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

Two sentences, front-loaded with purpose, and every phrase adds value. No fluff or repetition of obvious schema details.

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

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

For a tool with 9 parameters and an output schema, the description captures the core workflow, key constraints, and positioning relative to siblings. It does not list every parameter but the schema already covers that; the description is complete enough for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema: 'Body must be markdown' imposes a format constraint not in the schema, and it clarifies the integration between publish flag and go-live vs. draft. This compensates beyond schema.

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

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

The description opens with a specific verb and resource: 'Publish a blog post directly to WordPress without Notion.' It clearly distinguishes from sibling tools by naming create_post as an alternative when Notion is needed.

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

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

Explicitly states when to use this tool: 'Use this instead of create_post when you don't need Notion.' Also provides essential usage constraints like 'Body must be markdown' and the publish flag behavior.

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 known. The description adds value by disclosing the exact return content (status enum, progress steps, error message). No additional caveats are needed given the simple read-only nature and presence of an output schema.

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

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

The description is a single, front-loaded sentence that directly states the purpose and the key return elements. No unnecessary words or redundant information.

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

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

For a simple read-only tool with one parameter and an output schema, the description is complete. It covers what the tool does, what it returns, and the jobId source is documented in the schema. No significant gaps remain.

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

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

Schema coverage is 100% and the jobId parameter has a clear description, including where it comes from. The tool description does not add any extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool checks the status of a sync or publish job, using a specific verb ('check') and resource ('status'). It also includes the return structure (status, progress steps, error message), distinguishing it from list_jobs which lists all jobs.

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

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

The description implies usage when a jobId is available from create_post, update_post, or publish_post (as noted in the schema), but it does not explicitly state when to use this tool versus alternatives like list_jobs, nor mention any exclusions or 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 declare readOnlyHint=true and destructiveHint=false, so the tool's safe read-only nature is already clear. The description adds value beyond annotations by specifying the exact fields included in the response ('status, WordPress URL, and category'), giving the agent better expectations of the output.

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

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

One short, information-dense sentence. Every word adds value: it names the resource, the action, the required identifier, and the key return fields. No wasted words.

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

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

For a simple single-parameter read operation with a readOnlyHint, the description is mostly complete. It lists the important returned fields and the required ID. It could mention what happens if the post doesn't exist (404) or if the user lacks permissions, but given the read-only nature and available schema, this is adequate.

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

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

The schema already covers the only parameter (postId) with a description ('The post ID'), and coverage is 100%. The description adds context about what is returned but doesn't add specific syntax or format details about the postId parameter beyond what the schema provides.

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

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

The description uses a clear verb+resource ('Get details of a specific post') and specifies the data points returned ('status, WordPress URL, and category'). While it distinguishes itself from a general 'get' operation, it doesn't explicitly contrast with the sibling get_job or list_posts, though the name and description make the purpose evident.

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

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

The description implies usage for fetching post details by ID, which is useful, but it doesn't provide explicit guidance on when to prefer this over list_posts or update_post. It clearly implies a retrieval context, but no when-to-use or alternatives are given.

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

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

The annotations (readOnlyHint: true, destructiveHint: false) fully disclose the tool's side effects. The description is consistent with these annotations and adds no contradictory information. For a simple read operation, this meets the transparency bar.

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, succinct sentence that lists all relevant aspects without fluff. It is front-loaded with the core action ('Get your Notipo account configuration') and then enumerates specifics, making it easy to parse.

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

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

Given the simplicity of the tool (no parameters, read-only), the description fully covers what the user can expect: the type of data returned (settings related to services, plan, features, triggers). No additional context is needed for a getter of this nature.

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

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

The tool has no parameters, so the schema provides no information to augment. The description does not need to explain parameters; it correctly focuses on the return value. This dimension is trivially satisfied.

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: retrieving account configuration. It specifies the scope (services, plan, features, triggers) and distinguishes it from sibling tools like get_job or get_post by focusing on settings.

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

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

While no explicit 'when to use' is provided, the name and description make it obvious that this is the tool for retrieving account settings. The lack of parameters and the readOnly annotation further clarify usage, but explicit guidance on when to prefer this over other getters would be slightly more helpful.

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 known. The description adds that categories are synced to Notipo, implying the list reflects synced data, but doesn't detail return format or ordering. With annotations covering the read-only nature, a 3 is appropriate – it adds some context but not extensive behavior details.

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 sentence, front-loaded with the action and resource, and immediately adds a practical usage note. Zero waste.

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 there is an output schema (covers return values) and the description already states the purpose and usage, the description is complete enough. It doesn't describe error cases, but that's not necessary for a read-only list tool with high schema coverage.

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

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

The tool has 0 parameters, so the schema is empty. The description doesn't need to explain parameters. Baseline for 0 params is 4, and the description provides no parameter info because there is none. It appropriately focuses on the output's purpose.

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

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

The description clearly states it lists WordPress categories synced to Notipo, with a specific purpose: providing names for post creation. This distinguishes it from sibling tools like list_tags and list_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?

It explicitly says to use these names when creating posts, providing a clear usage context in relation to the create_post tool. It doesn't explicitly exclude alternative tools, but the context is clear enough for the listed siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's main addition is 'recent' and 'sync and publish,' which adds some context about scope. However, it doesn't disclose pagination, sorting details, or error behavior, which are not critical given the annotations but leaves room for more.

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 exceptionally concise, with two short sentences that communicate purpose and use case without any redundancy. Every word adds value, and it is front-loaded with the key action.

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

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

For a simple list tool with two optional parameters, an output schema, and comprehensive annotations, the description is adequate. It could mention default sorting (e.g., 'most recent first') to be slightly more complete, but this is a minor omission rather than a functional gap.

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

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

Schema description coverage is 100%, with limit and status fully documented, so the baseline is 3. The description adds no additional parameter-specific meaning beyond what the schema already provides, but it doesn't need to since the schema is comprehensive.

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

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

The description clearly states the tool lists 'recent sync and publish jobs,' using a specific verb-resource pair. It distinguishes from sibling tools like list_posts or get_job by specifying the job type and recency, making its purpose unambiguous.

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

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

The phrase 'Useful for monitoring pipeline activity' provides clear contextual guidance for when to use this tool. It doesn't explicitly mention alternatives or exclusions, but the context is sufficient given the tool's simplicity and sibling set.

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

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

Beyond the readOnly annotation, the description adds return field details (title, status, URL, category, timestamps), which helps set expectations. It does not mention potential limitations like pagination, but for a simple list operation this is sufficient.

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 fluff or redundancy. It clearly separates the action from the return content.

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

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

The description fully captures the operation's purpose and output for a simple list call. It lists the returned fields, which is sufficient given the lack of output schema.

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

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

The schema has no parameters, so no additional semantics are needed. The description correctly adds nothing about parameters, and the absence is appropriately reflected.

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

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

The description clearly states it lists all posts for the account, which distinguishes it from sibling operations like create or delete. The verb 'list' and explicit resource scope make the purpose unambiguous.

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

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

The description implies usage for viewing posts but does not explicitly state when to use it versus alternatives (e.g., search_calls) or any exclusions. The context is clear but lacks explicit 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, covering the safety profile. The description adds the 'synced to Notipo' context, but does not disclose any additional behavioral details such as pagination, ordering, or potential size. It does not contradict the annotations, so this is an adequate but not rich contribution.

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, focused sentences with zero filler. The description is front-loaded with the core action and resource, followed by a practical tip. Every word earns its place.

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

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

For a zero-parameter, read-only listing tool with an output schema and clear annotations, the description fully captures the tool's purpose and how to use the result. No additional information is necessary for an agent to correctly invoke it.

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

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

There are zero parameters, so the description has nothing to add about them. The baseline for 0 parameters is 4, and the description correctly focuses on output usage instead of 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 action ('List') and the specific resource ('all WordPress tags synced to Notipo'), and adds a practical usage hint ('Use these names when creating posts'). It distinguishes itself from sibling tools like list_categories and list_posts by explicitly mentioning tags.

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

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

It gives a clear context for when to use it (when creating posts that need tag names), but does not explicitly mention alternative tools or when not to use it. The purpose is clear enough to infer the usage, but it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-read, non-destructive operation. The description adds the state transition from draft to live, which is useful, but it does not disclose potential side effects, prerequisites (beyond 'draft'), or error conditions. This meets the lower bar set by the annotations but doesn't go further.

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

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

The description is a single sentence that is direct, front-loaded, and contains zero fluff. Every word contributes value; the parenthetical '(make it live)' reinforces the effect without verbosity.

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

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

The tool is simple (1 parameter), has complete schema coverage, a safety profile via annotations, and an output schema. The description conveys the core action and state change. It omits edge-case behavior (e.g., what if the post is not a draft?), but these are not critical for a straightforward publish operation.

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 100% coverage for postId with the description 'The post ID to publish'. The tool description adds no additional semantic meaning beyond that. Per baseline rules for high schema coverage, a 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 uses a specific verb ('Publish') and resource ('draft post to WordPress') with a clear state change ('make it live'). It distinguishes itself from siblings like create_post, update_post, and delete_post, clearly indicating this action transitions an existing draft to published status.

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

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

The usage context is implied by 'draft post' — it should be used when you have a draft to publish. However, it does not explicitly reference alternatives like direct_publish, nor does it state exclusions (e.g., when the post is already published). This is adequate but not explicit.

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

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

The annotations already declare readOnlyHint=false and destructiveHint=false, meaning it performs an action but is not destructive. The description adds useful behavioral context: it checks for posts with trigger statuses, queues jobs, has a cooldown, and requires Pro plan. This goes beyond the annotations and provides value.

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

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

Three sentences, each carrying essential information: action, trigger behavior, plan restriction, and cooldown. No wasted words, well front-loaded with the core purpose.

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

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

Given the tool's simplicity (no parameters, no request body), the description covers the key aspects: what it does, the statuses it checks, the plan requirement, and the cooldown. The output schema exists, so return values are structured. It could be slightly more detailed about what happens after the job is queued, but it's sufficient for a tool with no inputs.

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 0 parameters, so the schema covers everything trivially. The description doesn't need to explain parameters, but the baseline is 4 for 0 params. The description adds context about the action, but since there are no parameters, it fully describes the invocation scenario.

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 function: 'Trigger an immediate sync from Notion.' It specifies the resource (Notion) and the action (sync), and it mentions checking for posts with trigger statuses and queueing sync jobs, which distinguishes it from other tools in the sibling list (e.g., publish_post, direct_publish).

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

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

The description clearly implies when to use this tool: when an immediate sync is needed. It also mentions that it is 'Pro plan only' and has a '15-second cooldown between calls,' providing context for usage. However, it does not explicitly state when NOT to use it or mention alternatives, just a slight gap.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable behavior beyond that: it performs a partial update ('Only provided fields are updated') and triggers a re-sync to WordPress. It also notes the update happens in Notion first, which is not captured in annotations. These details provide useful transparency without contradicting 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 sentence that efficiently conveys the core behavior and the partial-update rule. It is front-loaded with the action and includes only necessary information. No fluff or redundant phrasing exists.

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 has an output schema (not shown) and annotations cover the write/non-destructive nature, the description covers the main behavioral points: updating content/properties and re-syncing. It does not mention error handling, prerequisites (like post existence), or the fact that postId is required, but these are implied by the schema and the nature of the tool. It is adequate for a straightforward update flow, though slightly more detail on side effects could be added.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds the crucial semantic that 'Only provided fields are updated,' clarifying that optional parameters are treated as partial updates and not reset if omitted. This goes beyond the schema's description of each field, enhancing the agent's understanding of parameter behavior.

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 'Update an existing post's content or properties in Notion, then re-sync to WordPress.' This specifies the verb (update), the resource (existing post), and the unique aspect of syncing to WordPress, which distinguishes it from siblings like create_post, delete_post, and publish_post. It is concise and unambiguous.

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

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

The description gives clear context: it is for updating an existing post, which implies it should be used instead of create_post or delete_post. However, it does not explicitly mention alternatives or when not to use it (e.g., for publishing a new post). No exclusions or comparisons are provided, so it meets the 'clear context, no exclusions' level.

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