xTiles

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

Annotations only flag it as a non-idempotent, open-world write; the description adds delivery mechanics (in-app feed + mobile push, no recipient), an ordering constraint (must be the very last calls of the turn, nothing after), batching semantics (one per changed place, never per task), and failure behavior (work stands, note the failure, retry at most twice). This is substantial context beyond the structured fields.

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

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

Front-loaded with purpose, then clearly segmented into WHEN and HOW, so it is navigable. It is nonetheless dense and repetitive in places (restating the no-notification-after-a-live-request rule), leaving a little fat despite every section being relevant.

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 four parameters, a 100% schema coverage, an output schema already present, and annotation coverage, the description fills the remaining gaps an agent needs: when it is appropriate, exact ordering, cardinality of calls, and recovery on failure. Nothing material is missing.

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

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

Schema coverage is 100% and the schema itself is unusually rich, so the baseline is 3. The description still adds value beyond the schema by making `title` mandatory on every call even though the schema does not require it, and by reinforcing the language/length constraints for text.

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 (create) and resource (notification) plus the exact scope: the owner of the account you're working in, about work they didn't watch happen. It also immediately clarifies there is no recipient parameter, which distinguishes it from anything resembling a messaging tool among the siblings.

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

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

Gives an explicit numbered WHEN list (scheduled/recurring run, explicit request, agreed schedule setup) and an explicit exclusion (never after an ordinary one-off live request, and do not offer one there). No other sibling competes for this behavior, and the conditions are unambiguous.

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

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

Annotations already cover the safety profile (destructive, non-idempotent, openWorld), but the description adds the top-level precondition and side-effect context not present in structured fields. It also clarifies the default-color behavior and the returned id. It does not elaborate on the destructive nature beyond the precondition, so 4 rather than 5.

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

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

Front-loaded with the core action, followed by parameter sourcing and then constraint/alternative guidance in a logical flow. Every sentence earns its place; nothing is redundant with the structured fields.

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

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

For a creation tool with an output schema, the description covers everything needed: what it does, required vs optional inputs, sourcing of view_ids, the top-level precondition, and the fallback path via xtiles_move_pages. Return values are covered by the output schema.

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

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

Schema coverage is 100%, so the schema already documents all four parameters in detail, making 3 the baseline. The description adds marginal value by pointing to xtiles_get_project_structure as the source for view_ids, but its "Omit color to use the app default" phrasing is slightly looser than the schema's "no colour set (not the same as DEFAULT)" clarification.

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 ("Group existing pages together in the tab bar") with clear scope. It is immediately distinguishable from siblings like xtiles_move_pages and xtiles_update_page_group, which it names as different operations. No ambiguity about what the tool creates.

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

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

Explicitly states the precondition (each page must be at the top level of the tab bar) and routes the agent to xtiles_move_pages when the page is already grouped. It also names xtiles_update_page_group for later recolouring, so the when/when-not/alternative guidance is complete.

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

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

Annotations already declare the safety profile (destructive, open-world, non-idempotent), so the description only needs to add context. It usefully discloses the return values (project_id, view_id, resource_url), the null case for resource_url when no view is created, and the automatic first-workspace fallback, all of which go 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 core purpose is front-loaded in the first sentence, and each subsequent sentence earns its place by adding a distinct fact (structure rules, requirement, return shape, default behavior). No filler or redundancy.

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

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

For a create tool with rich annotations and an output schema, the description is nearly complete: purpose, structural requirement, returns, and workspace default are all covered. It stops short of noting permission/auth needs or side effects on existing content, but those are largely carried by the annotations.

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

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

Schema description coverage is 100%, so both parameters are already fully documented. The description largely restates the same heading semantics and workspace fallback from the schema, adding little new meaning. Baseline 3 is appropriate when 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?

States a specific verb and resource ("Create a new xTiles project from Markdown") and defines the exact heading-to-entity mapping. This clearly places it at the project level versus sibling tools, but it never names an alternative (e.g., xtiles_create_view_from_markdown) to make the distinction explicit.

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

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

Provides a real prerequisite (at least one `##` heading, or the project cannot be created) and explains the workspaceId fallback, which contextualizes usage. However, it gives no explicit when-to-use-this-vs-sibling guidance, leaving the agent to infer this tool's place among the many other create_*_from_markdown variants.

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, idempotentHint=false, openWorldHint=true, so the safety profile is partly covered. The description still adds real value: the assignee requirement (an unassigned task never surfaces in the planner), the mandatory xtiles_get_current_user lookup, and the warning that the result carries no link so the agent must not fabricate one. However, for a batch multi-item create it says nothing about atomicity (what happens if one task in the array fails), duplicate-creation risk despite non-idempotency, or permission requirements.

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

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

The core action and its scope lead the text, and the alternative routes follow in a logical order. It runs long and repeatedly circles back to the tile-vs-task distinction, but given four competing destinations (own planner, checklist tile, project page, project task list) the length is largely earned.

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, yet the description still supplies the one return-value fact the schema cannot convey — that no link is returned, so tasks should be reported by title and due date. Combined with the prerequisite user-lookup step and the project routing rule, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents due-date formats, priorities, and assignee id/email. The description nonetheless adds decision semantics the schema cannot express: projectId changes which task list the task lands in, and assignees should default to the current user when unspecified. That is meaningful guidance beyond field documentation.

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 ('Create one or more tasks') plus the crucial scope qualifier ('in the person's own task list'). It explicitly demarcates itself from sibling routes — checklist-into-a-tile (xtiles_create_tiles_from_markdown_in_my_planner) and project-page tasks — so an agent can pick it without opening another schema.

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

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

Gives explicit routing rules: use here for the person's own tasks with planner language, use a tile for take/buy lists or instruction steps, do not use this tool for projects, and pass projectId only on explicit request. Both when-to-use and when-not-to-use are spelled out with named alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: tiles are appended rather than replaced, they arrive at one default size in import order, and a second `##` heading is refused. It does not address auth/permission requirements or any rate limits, so it is strong but not exhaustive.

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

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

Front-loaded with purpose and the preferred-over routing, then return shape, then next steps — a sensible priority order with no filler sentences. It is dense with stacked em-dash parentheticals, which costs some readability but each clause carries distinct 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 this complexity the description covers what an agent needs: target identification, append-vs-replace behavior, refusal condition, follow-up layout tools, and pointers to the design/palette resources. An output schema exists, yet the description still usefully names the return fields (view_id, tiles, parent_resource_url), leaving no substantive 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%, and both parameters are richly documented there (URL-to-viewId extraction, heading-to-tile mapping, append semantics, the `##` refusal). The description largely restates that material, so the baseline 3 for schema-documented parameters is appropriate.

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

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

States a specific verb+resource (append tiles generated from Markdown into an existing view/page) and immediately scopes it to the `viewId`-only path. It explicitly names the sibling it supersedes (`xtiles_create_tiles_from_markdown_in_view`) and why, so an agent can distinguish it from the near-identical creation tools without opening any schema.

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

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

Gives an explicit preference rule ('Preferred over ... — no `projectId` needed') plus the follow-up sequence (`xtiles_get_page_layout`, then `xtiles_set_page_layout` for the returned ids) and where the design rules live. When-to-use and what-to-do-next are both spelled out.

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?

Adds substantial detail beyond the annotations: tiles are appended to existing content rather than replacing it, all tiles land on one existing page, a second '##' is refused, and the returned view_id/tiles/parent_resource_url shapes are described. It also surfaces the precondition to read existing tile colours and continue the palette before writing, which an agent could not infer from destructiveHint/openWorldHint alone.

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?

Front-loaded with the core action and result, then workflow and guidance, with no filler sentences. It runs dense in its back half with multiple resource pointers, which slightly taxes scanning but each pointer is actionable.

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?

All three required parameters are anchored by ISO date semantics, period values, and markdown structure mapping, plus explicit pointers to the overview and design resources. With an output schema present and the return shape still summarized, nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not carry — default uniform tile size, import-order appending, and the palette-continuation requirement tied to inline colour values. The heading-to-tile mapping largely duplicates the schema text, keeping this short of a 5.

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 with scope: 'Append tiles generated from Markdown into your personal planner for the period containing the given date.' The 'personal planner' scope inherently separates it from the project-planner and by-view siblings, so an agent can pick correctly without opening schemas.

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

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

Gives clear operational context and next steps: tiles arrive at one default size in import order, arrange them via xtiles_get_page_layout then xtiles_set_page_layout, and points to the design guide for formatting decisions. It never states an explicit when-not-to-use or names the alternative markdown-import siblings, so it stops short of a 5.

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

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

Annotations already establish write/destructive/openWorld/non-idempotent semantics, and the description usefully adds that content is appended rather than replaced, that tiles arrive at a single default size in import order, and what the return envelope contains. It could say more about what 'destructive' means here (how existing layout is affected) given destructiveHint=true, but the append semantics are a real addition.

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

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

Purpose is front-loaded in the first sentence, followed by return shape and then next-step guidance; every sentence is load-bearing. Minor overlap with schema content (append-not-replace) keeps it from a 5.

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

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

For a 4-required-param write tool with an output schema and full annotation coverage, the description supplies the workflow chain, required pre-reads, and design-rule references an agent needs. Describing return values is partly redundant with the output schema, but nothing important 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 every parameter is already documented, and the description merely restates date ('period containing the given date') and markdown conversion at a high level. It adds no format, constraint, or edge-case detail beyond the schema, 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 specific verb+resource+target: 'Append tiles generated from Markdown into a project planner for the period containing the given date.' The phrase 'project planner' cleanly separates it from the sibling variants in_my_planner and by_view, so an agent can route without opening the schema.

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

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

Gives clear forward context — tiles arrive at one default size in import order, so arrange them next via xtiles_get_page_layout then xtiles_set_page_layout using the returned ids — plus prerequisites (read tile colours before writing) and pointers to the design rules. It does not explicitly compare against the in_my_planner or by_view siblings, which is the only missing 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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true — so the agent knows this is a mutating, non-idempotent operation. The description adds useful behavioral rules about the '##' heading limit (a second is refused) and describes the return values (view_id and resource_url), which goes beyond annotations. At the same time, it doesn't expand on destructive implications or permissions needed. A 3 is fair given annotations carry much of the burden.

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?

Well-structured and front-loaded: purpose first, then key rules about markdown, then discovery hint. Slightly dense with boilerplate around heading syntax (which is also in schema), but every sentence has a role. Not verbose but could trim redundant markdown 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?

For a mutation tool with full annotations and a 100% covered schema, the description is fairly complete. It defines the resource creation context, the one-page-per-call constraint, alternatives for multi-page creation, and the return values. With output schema present, it needn't explain the return object further. It's missing explicit mention of permissions or rate limits but those may not be applicable.

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 thoroughly documents both parameters, including the markdown heading rules and a pointer to the syntax guide. The description's markdown heading guidance duplicates what's in the schema's parameter description. Baseline 3 is appropriate since the schema does the heavy lifting; the description doesn't add significant parameter semantics 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 and resource: 'Create a new view (page) inside an existing xTiles project from Markdown.' Identifies the prerequisite of an existing project. It does distinguish itself from siblings somewhat by mentioning xtiles_create_project_from_markdown for multi-page new projects, but the differentiation is a bit indirect — it doesn't sharply contrast with other create-tiles tools like xtiles_create_tiles_from_markdown_by_view.

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?

Clear usage context: use for one page at a time, call xtiles_create_project_from_markdown for a new multi-page project, and xtiles_list_projects to find the projectId. It names alternatives and the condition selecting them. However, it doesn't say when NOT to use this vs xtiles_create_tiles_from_markdown_by_view, which is a closely related sibling.

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

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

Goes well beyond the annotations: annotations declare destructiveHint=true, but the description specifies THIS IS PERMANENT with no undo, gives concrete error semantics (404 for another project, 409 for planner day), and explains the approval workflow. This is rich behavioral context that the annotations cannot convey.

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

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

Front-loads the core action and key constraints, and the information is well-organized. However, it is somewhat long and includes some repetition (e.g., 'only pages listed by xtiles_get_project_structure are valid' restates the viewId source), and the final clause about approval could be tighter.

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?

Complete for a destructive mutation tool: it covers prerequisites (viewId source, project scope), error conditions, alternatives for reversible archiving, planner-day handling, and user-approval expectations. With an output schema present, return values needn't be described.

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

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

Schema coverage is 100%, so the schema already documents both parameters (viewId and projectId, including their sources). The description reinforces that viewId must come from xtiles_get_project_structure, adding a small amount of validation context, but mostly repeats schema information.

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

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

States a specific verb (Delete) and resource (a page from the project's tab bar), and distinguishes itself from closely related siblings like xtiles_update_page (archive), xtiles_get_planner_content, and planner tile creation tools. An agent can identify the exact operation without opening the schema.

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

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

Provides explicit when/when-not guidance: only pages from xtiles_get_project_structure are valid, planner days are excluded with specific error codes (404/409), and it names alternatives (xtiles_update_page with is_archived: true for reversible removal, xtiles_get_planner_content / xtiles_create_tiles_from_markdown_in_project_planner for planner days). It also clarifies approval handling and when to ask the user again.

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, but the description adds substantial context beyond them: it specifies exactly what is destroyed (the group only, pages are ungrouped, not lost), warns of the 409 refusal on system groups, and points to a reversible sibling. This is unusually rich behavioral disclosure.

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?

Front-loaded with the action, then semantics, then the alternative, then the hard constraint. Every sentence earns its place despite the length; the corrective all-caps clause is justified because the naive assumption (deleting a group deletes pages) is the main risk.

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. Given a mutation tool with two required params and rich annotations, the description covers everything an agent needs to invoke it safely and 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% and both parameters are documented there, including the groupId source and the system-flag caveat, so the schema does the heavy lifting — baseline 3. The description mostly repeats this guidance rather than adding new syntax or format detail.

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 page group from the tab bar) and immediately clarifies scope by distinguishing it from what it is not — pages survive. An agent can tell this apart from xtiles_delete_page and xtiles_update_page_group without opening 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?

Gives explicit when-to-use (safe tidy-up), names the alternative verb and exact parameter for the adjacent goal (xtiles_update_page_group with is_archived: true, reversible), and states a hard when-not (never target a group whose system flag is true). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the key operational fact that approval happens client-side before execution, telling the agent not to re-confirm in chat. It also reinforces permanence ('cannot be undone'), which is implied but usefully restated.

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?

Front-loads the action and scope, then adds the permanence warning and approval behavior. It runs a bit long with three sentences, but each carries actionable information rather than filling space.

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

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

With an output schema present and full parameter coverage, the description supplies the remaining operational context (permanence, external approval, project vs personal) that an agent needs to call it correctly without over-confirming.

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

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

Schema coverage is 100% and the schema already documents taskIds and the projectId omit-for-personal behavior, so the description adds little beyond it. Baseline 3 applies when 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?

States a specific verb ('Delete') and resource ('tasks by IDs') and immediately clarifies the projectId vs personal-task scope, which distinguishes it from page-deletion siblings like xtiles_delete_page.

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 tells the agent when to act versus ask: 'when the user has named what to delete, delete it rather than asking again; ask only when you cannot tell WHICH item they meant.' It also names the projectId condition for project vs personal tasks.

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

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

Annotations already cover readOnly/idempotent/no-destructive, so the bar is lower. The description still adds genuinely useful behavioral facts beyond them: output is CSV, the header reflects the chosen view's visible columns, pagination applies, and no server-side filtering exists yet. It does not cover rate limits or CSV encoding details, keeping it short of a 5.

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

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

Three sentences, front-loaded with the action and format, followed by the prerequisite and the filtering caveat. No filler; each sentence carries information the agent needs.

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

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

An output schema exists, so return values need not be described. Combined with annotations and a fully documented schema, the description supplies everything else an agent needs — prerequisites, format, filtering limitation — with nothing material missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that collection_view_id determines which columns appear in the CSV header and that column types/IDs come from the collection schema — real semantic context for two of the five 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 (Fetch), resource (rows from an xTiles collection/database view), and output format (CSV with pagination) in the first clause. It is clearly distinguishable from the sibling xtiles_get_view_content, which it explicitly casts as a prerequisite rather than an alternative.

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 an explicit prerequisite chain: call xtiles_get_view_content to read collection.views[] and pick a collection_view_id. It also states when-not/how-to-work-around: server-side filtering is unavailable, so filters must be applied client-side or via paging.

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

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

Goes well beyond the annotations: it discloses that URLs are parsed and resolved locally against the caller's own resources and never fetched from the named host (openWorldHint=false context), explains the 400/422/404/403 error semantics, and instructs the agent to report 403 ambiguously to avoid leaking private-id existence. This is unusually rich, honoring real security and UX constraints.

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

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

Front-loaded with purpose and usage, then structured into link shapes, resolution semantics, return values, and error codes. Dense but every sentence carries information. Slightly long for a one-parameter tool, but the density is warranted by the URL-shape complexity.

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 exists, the description adds the crucial interpretation layer the schema cannot: distinguishing resource_type=TILE for a card, clarifying that a tile link returns the tile's own markdown, pointing to the follow-up tool for the full page, and decoding the 403 ambiguity. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is already 100%, with the schema itself explaining the query-string distinction between page and tile links. The description reinforces this with worked examples of accepted URL shapes and reiterates that a bare id is rejected. It adds semantic depth rather than restating the schema.

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

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

States a specific verb and resource ('Resolve any xTiles link to the content it points at') and explicitly distinguishes itself from the nearest sibling by naming xtiles_get_view_content as the correct tool when the user already has a viewId. The link-shape taxonomy makes the scope unmistakable.

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

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

Tells the agent exactly when to use it ('whenever the user pastes an xTiles URL instead of guessing which id it contains') and when not to route here ('If you already have a viewId, call xtiles_get_view_content instead', repeated in the description's follow-up guidance). The 'paste the link as-is' instruction removes a common failure mode.

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=false, so the safety profile is covered. The description adds the returned field list, which is largely redundant given the output schema, and says nothing about auth prerequisites or error 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?

Two tight sentences: the purpose leads and the usage condition follows, with no filler or 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 an output schema covering return values and annotations covering the safety profile, the description only needs purpose and usage, both of which are present. It could still note that this is the canonical way to obtain the current user's id rather than searching, but nothing essential 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 there is nothing for the description to disambiguate; baseline 4 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 (Get) and resource (profile of the currently authenticated user) and enumerates the returned fields. The 'currently authenticated user' scoping clearly distinguishes it from siblings like search_users and get_user_timezone.

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

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

Gives a concrete when-to-use condition: assigning tasks to the current user when no explicit assignee was specified. It does not name alternatives (e.g., search_users) or state when not to use it, so it falls short of the explicit-alternatives bar.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious context: these documents are also served as MCP resources and this tool is the fallback path. Return format is not described, but an output schema exists to carry that.

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?

Front-loaded with the core action, then prerequisites, then per-guide content — a sensible ordering with no filler. It is dense with URIs and repeats the resource-equivalence point already present in the schema's parameter description, which is minor redundancy.

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

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

Given a single enum-constrained parameter and an existing output schema, the description covers everything an agent needs: when to use it, when not to, the fallback rationale, and a map of which guide to read for which downstream task.

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 enum lists all six URIs, so baseline is already met. The description goes further by explaining what each guide contains (markdown syntax, colours/styles/layout, task placement and dates), which the bare enum values do not convey — though overview/canvas/collections/blocks are lumped together rather than individually characterised.

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 ('Fetch an xTiles guide/documentation document') plus the addressing scheme (`xtiles://guide/...` URI). It is unmistakably distinct from other get_* siblings, which retrieve project/content data rather than documentation.

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

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

Explicitly states the selection condition — use this only when the client cannot read MCP resources directly — and gives concrete prerequisites: read `xtiles://guide/markdown/overview` (plus canvas/collections/blocks) before calling any `*_from_markdown` tool. It names the sibling family it supports, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: text pages have a fixed layout that the response flags as not editable, and it defines the coordinate system semantics. It stops short of describing pagination or size limits for very tall pages.

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 purpose and scope are front-loaded in the first sentence, and the usage instruction follows. It is dense rather than padded, though the coordinate-system explanation and the guide URI reference add length that a terse agent may not need inline.

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 re-explained, yet the description still supplies coordinate semantics, the text-page edge case, and a pointer to the design guide for valid style/position values. Nothing an agent needs to call and interpret this read tool 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?

There is a single required parameter with 100% schema description coverage, including how to extract `viewId` from a page URL, so the schema already does the work. The description's coordinate discussion (x, y, w, h) describes the response shape rather than adding meaning to the input parameter, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource ("Read the grid layout of an xTiles page (view) by `viewId`") and enumerates the payload: every tile with title and grid position, grid width, visible height, and minimum tile size. This is clearly distinguishable from siblings like `xtiles_get_view_content` (content, not layout) and `xtiles_set_page_layout` (write counterpart).

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

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

Explicitly states the use case — "inspect tile placement and valid bounds before repositioning with `xtiles_set_page_layout`" — naming the alternative tool and the sequencing condition. It also covers a when-not case: on a text page the layout is fixed and the answer reports it as not editable.

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 non-destructive, so the safety profile is covered. The description adds only the period/anchor semantics and the personal-vs-project planner distinction, which is modest added context rather than rich behavioral 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?

Two tight sentences with no waste; the read scope is front-loaded and the parameter guidance follows. Slightly more than strictly needed but efficient.

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

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

For a read-only tool whose annotations cover the safety profile and which has an output schema, the description conveys what an agent needs: resource, period, and the personal/project branch. Nothing essential 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 the schema already documents all three parameters including the projectId omission rule. The description largely restates what the schema provides, so the baseline 3 is appropriate with no meaningful added value.

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

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

States a specific verb and resource: 'Read planner content', scoped to a period anchored on a date. It does not explicitly differentiate from siblings like get_project_content or get_collection_content, but the resource is named clearly enough to distinguish.

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 the projectId branch ('Provide projectId for a project planner, or omit for your personal planner'), which is usage context. However, it gives no explicit when-to-use vs. alternatives or exclusions relative to the many get_* siblings, leaving that to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds real behavior — cursor chaining via next_view_id, termination when it is absent, and the inaccessible_view_ids surface. It does not discuss any auth/permission requirements, but for a read tool that is a minor 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?

Front-loaded with the core purpose in sentence one, then pagination mechanics, then the description-tag visibility rule. Dense but every sentence carries information; the final clause about collection-page descriptions is complex but not 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?

An output schema exists, so return values needn't be spelled out, and the description still covers pagination protocol, the inaccessible-view case, and the description-tag visibility semantics. Nothing an agent needs to page correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond the schema by explaining the cursor contract (take next_view_id and pass it back as start_view_id) and the limit-1 pattern for single-page reads, which the schema does not convey.

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

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

States a specific verb (read) and resource (combined content of a project = concatenated views), and separates itself from siblings by naming xtiles_get_view_content as the single-view alternative. An agent can distinguish this from get_collection_content, get_content_by_link, and get_view_content without opening schemas.

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

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

Explicitly says how to page (start_view_id + limit) and routes the agent to xtiles_get_view_content for reading a collection page on its own, plus the limit-1 trick here. Clear context, though it does not state when NOT to use this versus get_collection_content or get_content_by_link.

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

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

Goes well beyond the readOnly/idempotent annotations: archived entries are NOT filtered out and this is the only way to find one to unarchive; system groups omit the `pages` field entirely rather than returning an empty list; writes to them yield a 409 and should not be attempted. This is exactly the kind of trait an agent could not infer from structure.

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?

Despite its length, the definition is front-loaded with the purpose and every sentence conveys a distinct rule (ordering, archived visibility, system-group omission, 409 behavior, planner routing). No filler or restated structured data.

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, yet the description still usefully explains the return shape (kind PAGE vs GROUP and their fields) precisely to justify the system-group edge case. For a read tool with rich annotations and a full output schema, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single projectId is already documented, so the schema carries the load. The description nonetheless ties projectId to downstream usage (planner reads use 'period + date + this projectId'), adding modest context beyond the schema.

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

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

States a specific verb and resource ('Read the structure of a project's tab bar: every page and group, top to bottom, with their ids') and distinguishes itself from the six sibling write tools it names. An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly says 'Call this FIRST' and explains why: every other tool in the group needs a viewId/groupId that only this call provides, then names each dependent sibling. It also routes the planner case to xtiles_get_planner_content and xtiles_create_tiles_from_markdown_in_project_planner.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the project/personal scope distinction but does not mention error behavior such as a missing or inaccessible task ID.

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

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

Two short sentences with no wasted text. The core purpose is front-loaded, followed immediately by the key parameter-selection rule.

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

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

The tool has an output schema, full schema description coverage, and rich annotations, so the description does not need to explain return values or safety. It covers the essential calling context, though it could more explicitly route agents away from list/search siblings when a specific task ID is known.

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 taskId and projectId are already documented. The description's note about providing projectId for project tasks or omitting it for personal tasks largely restates what the schema says, so it does not add much beyond the structured fields.

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?

Uses a specific verb and resource: 'Get a single task by ID.' The word 'single' helps distinguish it from sibling list-style tools like xtiles_list_tasks, though it does not explicitly name the alternative.

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

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

Provides context for the optional projectId parameter (project tasks vs personal tasks), but does not explicitly say when to use this tool rather than xtiles_list_tasks or another retrieval sibling. Usage is implied by 'by ID' rather than stated as selection 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 cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: color/color_size are null when there is no palette color, and on a text page the style is fixed and the response reports it as not editable. This disclosed edge-case behavior is genuinely useful 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?

Front-loads the core purpose and the primary usage guidance. The final clause about reading a palette before adding tiles and the external guide reference are mildly tangential and lengthen the description, but nothing is wasteful enough to be a real defect.

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

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

With an output schema present the return shape needn't be spelled out, yet the description usefully characterizes the key fields (title, color, color_size) and their null semantics. An agent has everything needed to call it correctly; the guide link is a minor extra.

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?

Only one parameter and schema coverage is 100%, so the schema already documents viewId (including URL extraction). The description adds no syntax or format detail beyond what the schema provides, 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 specific verb (read) and resource (color styling of every tile on a page), scoped by viewId. It clearly distinguishes itself from the sibling mutators xtiles_set_tile_styles and xtiles_reset_tile_styles.

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

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

Explicitly says to use it to inspect current colors before recoloring with `xtiles_set_tile_styles`, and describes a second use case (reading an existing page's palette before adding tiles). It names the alternative tool and the conditions that select this 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 cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description earns credit for adding operational context beyond them: it discloses that the result carries both an IANA `timezone` string and `utc_offset_minutes`, and warns that the offset can be wrong for future dates due to DST transitions, telling the agent which field to use.

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?

Front-loaded with the outcome, then the usage trigger, then the DST caveat. Three sentences, each carrying distinct information with no redundancy or filler.

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

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

With an output schema present, the description needn't detail return values, yet it supplies the one non-obvious caveat (which field to trust for future dates). Zero params plus full annotations mean nothing else is missing 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter explanation because there is nothing to explain.

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

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

States a specific verb+resource extremely clearly: 'Get the current user's timezone and local datetime.' The scenario framing (before creating/updating/filtering tasks by due date) implicitly and effectively separates it from the closest sibling xtiles_get_current_user, which returns profile data instead.

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 an explicit trigger — 'Call this before creating, updating, or filtering tasks by due date' — which is exactly the when-to-use an agent needs. It does not name an alternative tool for the same job or state any when-not condition, so it stops short of full routing 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, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavioral context: what a regular page returns (title plus markdown body), how a description surfaces as a <description shown=...> tag and that no tag means no description. The return-format detail partially overlaps with the existing output schema, which keeps this from a 5.

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

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

Front-loaded with the core action and the discriminated return cases; each sentence conveys actionable information (return shapes, description tag semantics, follow-up tool). It is longer than strictly necessary but nothing is filler.

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

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

For a single-parameter read tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: what gets returned for each page type, how descriptions appear, and which tool to call next for collection rows.

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 viewId schema description already documents URL-extraction and ID discovery, so the schema does the heavy lifting. The tool description adds no parameter-level syntax or format details beyond what the schema provides, making the baseline 3 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 (read) and resource (content of a specific xTiles view/page) scoped by viewId, and clearly distinguishes the two shapes it can return (regular page vs. collection page). It names the sibling to route to for collection rows, so an agent can tell it apart from xtiles_get_collection_content without opening 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?

Gives explicit when-to-use guidance for both cases and an explicit next step: for collection pages, follow up with xtiles_get_collection_content using one of the listed collection view IDs. It also states the read-before-write rule for descriptions (read before changing, since xtiles_set_page_description replaces the whole description).

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

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

Annotations already establish the safe read-only, idempotent profile, but the description adds genuinely non-redundant behavior: the payload is advisory ('suggested steps, not commands'), no schedule executes server-side, and consent is required before creating anything recurring. It also flags that scheduling requires offering xTiles notifications, which is an operational trait the agent could not infer from `readOnlyHint`.

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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries a distinct instruction rather than filler. It runs long for a single-parameter read tool, and the scheduling/notification guidance is slightly tangential, but nothing is redundant enough to waste the agent's attention.

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

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

The tool has an output schema, so return-shape detail is unnecessary, and the description correctly focuses on how to interpret and act on the output instead. Given the low structural complexity (1 param, no nesting) it covers everything an agent needs to call it and use the result responsibly.

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?

One parameter with 100% schema description coverage — the schema already explains that the id must match a value from `xtiles_list_workflows` and gives an example. The description restates the discovery path without adding format or constraint detail, 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 specific verb and resource ('Fetch a prepared xTiles workflow by id') and then defines the resource in terms of what the agent will actually receive ('a recipe the xTiles team wrote for this kind of request'). This is enough to distinguish it from the sibling `xtiles_list_workflows`, which is named as the discovery 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?

Explicitly routes the agent: call `xtiles_list_workflows` first to discover ids, then treat the returned Markdown as reference material rather than executable commands, and adapt or skip steps. It also gives a decision rule for the awkward case (recurring recipes → ask the user before setting anything up), which is exactly the kind of when/when-not guidance that prevents misuse.

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

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

Annotations already cover readOnly/idempotent/destructive, but the description adds real behavioral context beyond them: the overlap rule (any part of an event inside the window puts it on both days), the ambiguity of an empty list vs. no calendar connected, and the read-only guarantee restated as user-facing scope.

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?

Four short sentences, front-loaded with what the tool does, then scope, then defaults, then edge-case semantics. No sentence is filler; each carries a distinct operational fact.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent needs: default window, overlap behavior, empty-result ambiguity, and the complementary tasks tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description nevertheless adds window semantics not in the schema — the ANY-overlap matching rule and the explicit contrast with xtiles_list_tasks' single-due-date matching. It does not add further detail on page/per_page, which the schema already handles.

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 (list) and resource (events from the user's connected Google and Outlook calendars), and explicitly contrasts the tool with xtiles_list_tasks. An agent can distinguish it from the ~37 siblings without opening the schema.

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

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

Gives explicit defaults ('with no dates, returns today'), states what an empty result does and does not mean, and routes the agent to call both this and xtiles_list_tasks for a complete day view. When-to-use and when-to-combine are both covered.

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 structurally. The description adds useful behavioral context about the returned data (workspace names/IDs plus contained projects), which goes beyond what the annotations state.

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

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

Three short sentences, front-loaded with what is returned, then the navigation hint. No filler, no repetition of the title or annotations.

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 annotations covering safety, an output schema covering the return structure, and no parameters to explain, the description only needs to convey purpose and usage — and it does both. Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description's note about discovering projectId values is a helpful clarification of the tool's role even though it is not a 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 names a specific verb and resource and clarifies the unusual shape of the result set: workspaces together with the projects nested inside each. It is unambiguous what the tool returns, but it never contrasts itself with the sibling xtiles_search_projects, which an agent could plausibly confuse with a 'list projects' 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?

"Use this to discover available projectId values for other tools" gives a concrete, actionable usage context rather than leaving the agent to guess. It stops short of exclusions — it does not say when to prefer xtiles_search_projects or xtiles_get_project_content over this listing.

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, destructiveHint=false, and non-open-world behavior, so the safety profile is covered structurally. The description adds the project-versus-personal scope distinction, but says nothing beyond annotations about defaults (e.g., completed=false returning only open tasks) or pagination 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?

Two short sentences, front-loaded with the core action and followed by the key scoping decision. No filler or restatement of the tool name beyond what is necessary.

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 fully described 9-parameter schema, rich annotations, and an output schema, the definition needs only high-level scoping context, which it provides. It could mention that the default result set is limited to open tasks and that results are paginated, but those details are recoverable from the schema.

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

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

Schema description coverage is 100%, including detailed semantics for due_date_after/before, priority, sort, and page size, so the schema carries the burden. The description only echoes the projectId behavior already documented in the schema, adding no new parameter meaning; 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?

The description states a specific verb and resource ('List tasks') and immediately clarifies the two scoping modes: project tasks via projectId versus personal tasks when omitted. It is clear enough to act on without opening the schema, though it does not distinguish itself from sibling read tools like xtiles_get_task or xtiles_list_projects.

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 concrete condition for projectId ('Provide projectId to list project tasks, or omit for your personal tasks'), which is useful routing guidance. However, it never names an alternative tool (e.g., xtiles_get_task for a single task) or states when not to use this tool, so guidance stops at the parameter level.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the response contains each workflow's id, title, and when-to-use note, and it prescribes the follow-up call to xtiles_get_workflow. It does not mention any auth or rate-limit considerations, keeping it short of a 5.

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

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

The critical instruction ('Call this FIRST') is front-loaded and the follow-up action is stated at the end. It is somewhat repetitive in restating the same routing idea twice ('If there is any chance a prepared workflow already covers the request, check here before improvising' after already saying 'Call this FIRST'), which costs a point but does not bury the payload.

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 the description is not obliged to explain return values, yet it still summarizes them (id, title, when to use it) and closes the loop by naming xtiles_get_workflow as the next step. For a zero-parameter discovery tool with full annotation coverage, nothing an agent needs 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 rubric the baseline is 4. There is nothing parameter-related the description could add, and it correctly spends no space on inputs.

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 ('List the pre-built xTiles workflows') and immediately defines what a workflow is ('curated, step-by-step recipes'), with concrete examples (digests, weekly reviews, briefs, onboarding). It clearly separates this discovery tool from the sibling action tools like xtiles_create_tasks or xtiles_get_workflow.

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 an explicit imperative to call this FIRST before assembling multi-step processes by hand, enumerates the triggering intents (set up, automate, schedule, onboard, 'have xTiles do something for them'), and names the alternative path ('proceed normally with the other tools' / improvising with individual xtiles_* tools) when nothing matches. This is close to ideal routing 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 cover destructive/idempotent/openWorld, but the description goes further: it discloses the exact 409 failure conditions for system groups, warns that passing null silently moves pages out of a group while still reporting success, and notes the API returns no body on success along with the recommended follow-up call. This is rich context beyond the structured fields.

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

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

Purpose is front-loaded in the first clause and every sentence carries information (destinations, restrictions, position semantics, response behavior). It is dense and delivered as one long run-on paragraph rather than structured sections, which slightly hurts scannability.

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

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

With an output schema present, the description needn't explain return values, and it still notes the empty response body. For a 4-parameter mutation tool with a nested position object, the guidance on prerequisites, restrictions, and follow-up is 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 coverage is 100%, so baseline is 3. The description does add value: it frames group_id as the destination (never the current location), stresses relative_to_id must be a page id never a group id, and clearly marks position as optional-and-usually-omitted. Much of this overlaps the schema text, but the 'do not invent a position' guidance meaningfully sharpens intent.

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 (move/reorder) and resource (pages in the tab bar) with three explicit modes: into a group, out to the top level, or to a new position. This clearly distinguishes it from siblings like xtiles_update_page, xtiles_set_page_layout, or xtiles_move-like group 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?

Explicitly says where to get view_ids/group_id (xtiles_get_project_structure), when to set group_id to a real id vs null, when to omit position (append is 'almost always' correct), and when position is warranted. It also names the exclusion cases (system-flag groups, pages already in a system group) and the resulting 409.

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 destructiveHint=true and idempotentHint=false, but the description goes far beyond them: atomicity of all replacements, the exactly-once matching requirement, empty new_str as deletion, heading-level rules that cause rejection, what is silently preserved (file blocks, dividers, table column types, styles), and the fact that the page description is excluded from matching. No contradiction with the destructive 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?

It is long and densely capitalized, but the core workflow and the primary constraint (old_str must match exactly once) are front-loaded before the edge cases. For a mutation tool with such non-obvious semantics each block of text carries weight, though the volume is close to the limit of what an agent can absorb.

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?

Output schema exists, yet the description still notes the success return (updated markdown) and that rejections explain what to do instead. For a complex, destructive in-place edit with unusual heading and table rules, the coverage appears complete: workflow, failure modes, preserved content, and boundaries with sibling tools are all addressed.

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 baseline is 3, and the description adds real meaning the schema lacks: one old_str may span several blocks or cross tile headings, may cover only part of a block, and can express reordering, merging, or splitting. It also reinforces the exact-match and empty-deletion semantics of both 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?

It states a specific verb and resource ('Edit a page in place by search-and-replace over the markdown') and names the sibling whose output it operates on (xtiles_get_view_content). It also explicitly separates itself from xtiles_set_page_description and the collection API, so an agent can route correctly without opening a 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?

It gives an explicit workflow (read, copy the exact substring, send replacements), states the ambiguity-handling rule, and names alternatives for adjacent cases: xtiles_set_page_description for the description, the collection API for database pages, and delete+add for a table that must become non-table content. When-to-use and when-not-to-use are both covered.

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 destructiveHint=true and idempotentHint=true; the description meaningfully bounds that destruction ('structural style (icon) and any custom workspace color are left unchanged') and discloses a failure mode (text pages are refused). The closing note about the return value is redundant with the existing output schema, but the scope-of-damage disclosure is genuine added 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 front-loaded sentences with the destructive action and its limits stated first. The final sentence restates a return value already covered by the output schema, which is the only wasted line.

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, complete annotations, and an output schema, the description covers everything an agent needs: what is cleared, what survives, the refusal case, and the fact that this is idempotent and destructive.

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%, including an example for extracting viewId from a URL and a pointer to xtiles_get_tile_styles for tile_ids. The description adds no format or syntax detail beyond the schema, 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 precise verb ('Clear') and resource ('palette color (`color` and `color_size`) of the listed tiles'), plus the exact boundaries of that resource. It implies the inverse relationship to xtiles_set_tile_styles but never names that sibling, so an agent still has to infer the pairing.

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

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

Provides a firm when-not condition — 'A text page's tile style is fixed — the call is refused there' — and implicitly handles the when-to-use case via the reset-vs-set distinction. It does not explicitly name xtiles_set_tile_styles as the alternative for setting rather than clearing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety carries less burden. The description adds useful behavior beyond them: what comes back ('projects with their views (pages) and highlighted snippets') and that matching is full-text over titles/content. Pagination behavior is left to the 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?

Three short sentences, front-loaded with the operation and result shape before the routing hint. Every sentence earns its place with 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?

With an output schema present, return-value details need not be spelled out, and the description still adds the snippet/view context. Pagination defaults and limits live in the schema, so what remains for the description is complete enough to call 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% and fully documents page, size, and text (including the contrast with xtiles_list_projects). The description adds nothing parameter-specific beyond the general notion of a free-text query, 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 specific verb and resource ('Full-text search across projects') and even describes the result shape ('matching projects with their views (pages) and highlighted snippets'). It does not explicitly name the sibling it should be used instead of (xtiles_list_projects appears only in the schema's text param), so sibling differentiation is left implicit.

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?

'Use this when the user references a project by name or topic rather than ID' gives a clear triggering condition. It stops short of naming the concrete alternative (xtiles_list_projects) or stating exclusions, so it is clear context rather than a full when/when-not map.

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

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds a real behavioral constraint the annotations do not: results are scoped to people you share a workspace or project with, meaning zero global results are possible.

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

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

Two compact clauses with no filler; the scope constraint and the not-global warning come first, and the practical use case is last. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained. Scope, exclusions, and purpose are all covered for a simple two-parameter lookup; only edge behavior such as no-match results is unaddressed.

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 both query (name or email) and limit (1–50, default 10) documented inline. The description echoes the query semantics but adds nothing about format, matching behavior, or empty results, so it sits at the baseline.

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

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

States a specific verb (search) plus resource (people/users) and immediately bounds the scope to shared workspace or project members. This distinguishes it cleanly from a global directory lookup, which no sibling tool covers.

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 excludes the wrong interpretation (not a global directory) and gives a concrete use case — finding user IDs for task assignment. It falls short of naming an alternative tool when the search fails (e.g., get_current_user), so it is strong but not fully routed.

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 flag destructiveHint and idempotentHint, but the description adds the crucial detail of WHAT is destroyed: the whole description is replaced, not merged. It also states the return payload (stored description plus shown flag). Lacks only peripheral context like permission requirements, which is minor for a single-field setter.

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 with zero filler; the core set/clear behavior is front-loaded, followed by the replacement caveat and the return contract. Every sentence carries information an agent needs.

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

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

For a simple two-parameter setter with a documented output schema, the definition covers purpose, both modes, replacement semantics, and the read-before-write workflow. Nothing essential 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 coverage is 100% and the schema already documents empty-string clearing, inline Markdown support, and multi-line text, so the description largely restates it. The only added nuance is that formatting is normalized on save ('with the formatting that was kept'), which is marginal.

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 (set/clear), resource (page/view description), and key identifier (`viewId`) in the first clause. An agent can immediately distinguish this from siblings like `xtiles_update_page`, `xtiles_set_page_layout`, or `xtiles_patch_view_content`.

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 covers both operation modes (non-empty to set/show, empty string to clear/hide) and names the alternative workflow for partial edits: read the current text with `xtiles_get_view_content`, then send the full new text. The condition that selects each path is unambiguous.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing partial-update semantics ('Only the listed tiles move; the rest keep their current position'), server-side validation rules, the minimum-size exception, the text-page refusal, and that the full resulting layout is returned. These are exactly the mutation-behavior details an agent needs before committing a destructive layout change.

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 core content is front-loaded and useful, but a large block is agent-directed meta-instruction ('check it silently before replying… Nothing of the check goes into the reply') plus a bare policy citation ('Rules: `xtiles://guide/markdown/design`, Step 3') that adds length without adding tool-selection value. Roughly a third of the text does not earn its place in a tool definition.

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 the brief 'returns the resulting full layout' suffices, and the annotations carry the safety profile. Complete enough to call correctly; the only drag is the buried verification guidance, which is better expressed as validation rules than as an instruction to the model.

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 nested item fields already document x/y/w/h meaning and the out-of-bounds/overlap/uniqueness constraints. The description's coordinate explanation ('(x, y) is the top-left corner and (w, h) the size, in grid cells') largely restates the schema, so the baseline 3 applies rather than a bonus.

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 — 'Reposition tiles on an xTiles page (view)' — and immediately disambiguates from the read-side sibling by naming `xtiles_get_page_layout` as the prerequisite. An agent can distinguish it from `patch_view_content` or `update_page` without opening 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?

Gives an explicit prerequisite workflow ('call `xtiles_get_page_layout` first to get tile IDs and current positions'), an explicit exclusion (text pages refuse the call), and the failure conditions that will reject the call. The only missing element is a named alternative for restructuring content, but the when/when-not is otherwise complete.

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 cover the safety profile (readOnly=false, destructive=true, idempotent=true, openWorld=true), but the description adds real behavior beyond them: the operation merges rather than replaces (icon and custom workspace color preserved), omission is a no-op per field, and the call is refused on text pages. It also states the return payload is the full resulting tile-style state. Minor tension: destructiveHint=true sits a bit oddly against the emphasis on preservation, but the description never claims a read-only or lossless-free operation, so this is not a contradiction.

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?

Four dense sentences, each carrying distinct information (scope, merge behavior, per-tile requirement, refusal case, ID discovery, design reference). Front-loaded with the operation itself and no repetition of schema enums.

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

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

For a mutation tool with a rich enum schema, nested item objects, and an output schema, the description supplies everything an agent still needs: how to obtain IDs, the refusal condition, merge/omit semantics, and the fact that the result is returned. Return-value details are correctly left to the output schema.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds genuine semantics the schema does not encode: 'provide at least one of color/color_size per tile' is a cross-field constraint, and the merge/omit semantics explain what each optional field does when absent. The viewId URL-extraction hint is also useful context.

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: 'Set the `color` and/or `color_size` of one or more tiles on an xTiles page (view).' This cleanly separates it from the read siblings (xtiles_get_tile_styles) and the reset sibling (xtiles_reset_tile_styles), and it names the exact fields it mutates.

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 concrete preconditions and exclusions: at least one of color/color_size per tile must be supplied, omitted fields are left unchanged, and text-page tiles are refused. It also points to `xtiles_get_tile_styles` for tile IDs and to a design guide resource. It stops short of explicitly contrasting with xtiles_reset_tile_styles, the closest mutating alternative.

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, idempotentHint=true and openWorldHint=true, so the description carries a lighter burden, but it adds real context: partial updates across any combination of fields, the specific failure modes (404/409), and that the API returns an empty body on success. It does not cover permission/auth requirements, which is the main remaining 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?

Front-loads the action and the mutable fields, then the prerequisite, then the planner carve-out. It is dense and slightly digressive in the middle (planner routing), but each sentence supplies information an agent needs to avoid a wrong call.

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 and the description explicitly notes the API returns no body, so return-value expectations are handled. Combined with prerequisites, allowed IDs, error codes and partial-update semantics, nothing essential is missing 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 coverage is 100%, so the per-parameter descriptions already do the heavy lifting. The description still adds grouping semantics — 'provide title, color, is_archived, or any combination' — clarifying that this is a partial/patch-style update rather than a full replacement, which the schema alone does not state.

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 ('Update a page in the project's tab bar') and enumerates exactly what can be changed (title, colour, archive). It explicitly distinguishes the tool from planner-day writing, which is the main lookalike, so an agent can tell it apart from the create/patch siblings without opening the schema.

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

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

Gives the prerequisite source for `viewId` (`xtiles_get_project_structure`) and states the exclusion both positively and negatively: only pages from that structure are valid, a planner day is not, and it names the two sibling tools to use for planner days instead. Error semantics (404 cross-project, 409 planner page) reinforce the boundary.

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 annotations, it discloses that archiving a group also archives its pages, that system groups are rejected with a 409, and that success returns no body. These are meaningful behavioral details for a destructive mutation tool.

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

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

The description is front-loaded with the core operation and supported fields, then moves to constraints and API behavior. Every sentence adds useful information without redundancy.

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

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

Given the rich annotations, complete schema coverage, and output schema, the description supplies the remaining important context: side effects of archiving, the system-group prohibition, and the no-body success response. Nothing essential for 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%, so the schema already documents each parameter in detail, including the color enum and the system-group constraint. The description reinforces how groupId is obtained and what archiving does, but adds little parameter-level information 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 states a specific verb and resource (update a page group) and enumerates the exact mutable fields: title, color, and is_archived. It is clearly distinguishable from sibling operations such as create_page_group or delete_page_group.

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 clear guidance on how to obtain groupId from xtiles_get_project_structure and explicitly forbids targeting system groups because the API returns 409. It does not explicitly route the agent to sibling alternatives for creating or deleting groups, but the usage context is otherwise strong.

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, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the genuinely useful partial-update contract ("Only specified fields will be updated"), but says nothing about what destructive means in practice — e.g. that passing assignees replaces the existing list wholesale — or about permissions/irreversibility.

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 padding, and the scope rule is front-loaded ahead of the partial-update caveat. Nothing repeated and nothing wasted.

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 and annotations carry the risk profile, so much is covered structurally. However, for a destructive 8-parameter mutation the description never states that omitted fields are preserved while provided ones (notably assignees) are overwritten, nor any failure/permission conditions — gaps an agent would want closed.

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 schema already documents due-date formats, assignee replacement and projectId scoping in detail. The description adds no parameter-level meaning beyond restating the projectId rule, 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?

Names a specific verb and resource ("Update an existing task") plus the scope rule that distinguishes personal from project tasks. It does not explicitly contrast with siblings like xtiles_delete_tasks or xtiles_get_task, so sibling differentiation is left implicit.

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 projectId/omit rule gives a conditional, but this is really parameter scoping rather than when-to-use guidance. There is no mention of prerequisites (e.g. fetching the task first) or of which sibling handles deletion/creation instead.

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