xTiles

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

Adds real behavioral context beyond annotations: no recipient parameter, nothing sent externally, and the 100-character display cutoff. However, the annotations declare destructiveHint=true and idempotentHint=false, and the description says nothing about why this benign-sounding notification is flagged destructive or what happens on repeated calls. It also omits any rate-limit or failure behavior. Useful additions, but the destructive/idempotency profile is left unaddressed.

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 timing, then batching, all in short sentences with concrete examples. It is longer than strictly necessary — the final sentence about touching two places restates the preceding 'once per place' rule — but no sentence is 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, so return values need no explanation, and the batching/composition semantics are fully covered. The remaining gap is behavioral: no mention of the destructive flag, idempotency (duplicate notifications if called twice for the same place), or any limits, which is somewhat surprising given 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 the schema already documents all four parameters with examples and length limits. The description adds the relevant clarification that there is no recipient parameter and that url/summary are keyed to a single 'place', but it largely restates what the schema carries. Baseline 3 is appropriate.

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

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

States a specific verb and resource (create an in-app notification) and immediately scopes it: it targets the account owner's internal notification feed, not external recipients. No sibling tool competes for this role, and the description makes that distinct role explicit in the first sentence.

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 unambiguous timing ('AFTER you have finished all the work... not before or mid-way') and explicit batching rules: once per place touched, one combined summary, call twice if two places were touched. This is exactly the when/when-not guidance an agent needs and leaves 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 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 readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description adds non-obvious behavior the annotations do not: the default-assignee rule and the prerequisite ordering of xtiles_get_current_user, which materially changes how the agent calls the tool.

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

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

Three sentences, front-loaded with the action and scoping, then the prerequisite rule. No filler, no restatement of the name or schema.

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, and all parameters are documented. The description covers creation scope and the assignee default. It does not mention the required 'title' on each task or any batch/partial-failure behavior, which is a minor gap for a multi-item create.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning on top of the schema: projectId omission means personal tasks, and assignees default to the current user when unspecified. That is genuine semantic value beyond the field descriptions.

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 ('Create one or more tasks') and immediately scopes it (project vs. personal). This clearly distinguishes it from update_task/delete_tasks siblings, though it does not explicitly name any sibling. The core purpose is unambiguous.

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

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

Gives concrete conditional guidance: include projectId for project tasks, omit for personal tasks, and when no assignees are supplied, call xtiles_get_current_user first and default to the current user as assignee. That is a real workflow rule. It stops short of naming alternative creation paths (e.g. create_tiles_from_markdown_*), so not 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?

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, so the safety profile is covered. The description earns credit by reinforcing 'permanent and cannot be undone' and by disclosing the approval-handling model (client-side confirmation outside this call), which is behavioral context annotations cannot express.

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, then scope, then consequences, then the confirmation policy. All sentences carry useful information, though the closing sentence about when to ask in chat is longer than strictly 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 an output schema present, return values need no explanation. The description covers scope, permanence, batch deletion, and the human-approval contract, leaving nothing an agent needs in order to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the 'omit for personal tasks' semantics. The description restates this without adding syntax, ID format, or batch-size guidance, 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?

Specific verb plus resource: 'Delete one or more tasks by IDs.' It names the key input (IDs) and the scoping dimension (project vs personal), so an agent can immediately distinguish it from xtiles_create_tasks and xtiles_update_task.

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 context: supply projectId for project tasks, omit for personal tasks, and states the confirmation policy (client asks the user, so don't re-ask in chat when the target is named). It does not compare against sibling delete tools (e.g. xtiles_delete_page) or state when not to delete, 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 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 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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: cursor semantics, that next_view_id must be fed back as start_view_id, and that it is absent when paging is done. It does not discuss access-control implications of inaccessible_view_ids beyond naming the field.

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 dense sentences, front-loaded with the core action and scope before the pagination mechanics. Every clause carries information an agent needs; 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?

An output schema exists, so return values need not be explained, yet the description still summarizes the page payload (view_ids, inaccessible_view_ids, next_view_id) to close the pagination loop. Combined with full annotation coverage and 100% schema coverage, 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 both optional parameters and their constraints (limit 1–20, default 5; projectId discovery via xtiles_list_projects; start_view_id as cursor) are already fully documented. The description restates the start_view_id/limit pairing without adding syntax 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 and resource ('Read the combined content of a project') and clarifies the scope as 'concatenated views,' which implicitly separates it from xtiles_get_view_content and xtiles_get_project_structure. It stops short of naming those siblings explicitly, so an agent must infer the boundary.

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 concrete pagination guidance ('Use start_view_id + limit to page through a large project'), which is implied usage rather than an explicit when-to-use/when-not statement. It never says when to prefer this over xtiles_get_view_content or xtiles_get_collection_content.

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

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

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, and destructiveHint=false, so the safety profile is fully covered. The description adds only the namespace-switching behavior of projectId, and says nothing about permissions, error behavior, or lookup failures.

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 one conditional that matters. Nothing is padded or repeated.

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, and annotations cover the safety profile. For a two-parameter read tool this is essentially complete, with only the absence of sibling routing leaving a small gap.

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

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

Schema coverage is 100% and both parameters already carry descriptions, including the 'omit to use personal tasks' rule. The description restates that same rule rather than adding format, ID source, or validation detail 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 ('Get a single task by ID'), which cleanly separates it from list_tasks, update_task, and delete_tasks. It does not name a sibling explicitly, but the singular 'single task by ID' framing is unambiguous.

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

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

The description gives a conditional scoping rule (supply projectId for project tasks, omit for personal tasks), which is real usage guidance, but it never says when to prefer this tool over siblings like list_tasks or get_project_content. Usage is implied rather than framed against 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 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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the return shape differs by page type (markdown body vs collection schema with attribute ids/titles/types), which the agent needs to interpret the response.

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

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

Three sentences, each earning its place, with the core action front-loaded and the page-type branching plus the follow-up tool placed after it. No filler.

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

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

For a single-param read tool with full annotation coverage and an output schema, the description supplies everything else an agent needs: the two return modes and the escalation path to the sibling tool 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 coverage is 100% and the schema's own description already explains URL extraction and programmatic discovery, so the description adds little beyond 'by viewId'. 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 and resource ('Read the content of a specific xTiles view (page) by viewId') and then distinguishes two distinct behaviors (regular page vs collection page), which no sibling does. An agent can tell it apart from xtiles_get_collection_content or xtiles_get_project_content immediately.

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: for collection rows, 'follow up with xtiles_get_collection_content using one of the listed collection view IDs.' That names the alternative and the condition that selects it, so there is no inference required.

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, closed-world), but the description adds substantial non-obvious context: the returned Markdown is advisory reference material, not commands to execute verbatim. It also discloses that the server runs no schedules, so any recurring setup is client-side — a real behavioral caveat the annotations cannot express.

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, followed by discovery guidance and then interpretation rules; every sentence carries weight. It runs long (five sentences) and the trailing scheduling caveat drifts slightly beyond the fetch operation, but nothing is filler and the ordering is logical.

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 no explanation, yet the description still supplies the crucial interpretive framing (Markdown recipe = suggestions) that an agent cannot infer from the schema. With annotations covering safety and the schema covering the parameter, nothing needed to call and correctly use 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 description coverage is 100% and the single parameter is thoroughly documented, including an example id and the discovery pointer. The description's 'by id' and its reference to xtiles_list_workflows largely restate the schema, so it earns the baseline 3 rather than more.

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 goes further by defining what a workflow actually is ('a recipe the xTiles team wrote for this kind of request'). This makes it immediately distinguishable from siblings like xtiles_list_workflows, xtiles_get_docs, and xtiles_get_project_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 routes the agent: 'Discover ids with `xtiles_list_workflows` first' names the prerequisite tool and the condition that selects it. It also gives downstream usage guidance — walk the user through the recipe, execute agreed steps via `xtiles_*` tools, and ask before setting up anything recurring.

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 declare readOnlyHint=true, so safety is covered. The description adds the crucial scope behavior that projectId toggles between project tasks and personal tasks — a behavioral default beyond what annotations provide. It doesn't mention pagination defaults or the fact that only open tasks are returned by default, though the schema covers the latter.

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

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

Two concise sentences, front-loaded with the core action and directly followed by the critical scoping rule. No wasted words.

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

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

Given 9 optional parameters, no required ones, and a complete schema, the description covers the essential scope decision and filter hint. With an output schema present, return values need not be described. The only minor gap is not mentioning pagination or default sort, but these are well-covered in 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 coverage is 100%, so parameters are fully documented. The description adds the explicit projectId semantics (project vs personal) which, although also in the schema, reinforces the branching logic. Filters are implied but not enumerated, which is acceptable given schema completeness.

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 ('List tasks') and immediately disambiguates scope: project tasks via projectId vs. personal tasks when omitted. This scoping detail distinguishes it from siblings like xtiles_get_task and 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?

Gives clear context for the primary branching decision (projectId present vs. absent) and lists optional filters. However, it doesn't reference alternatives like xtiles_get_task or xtiles_search_projects, nor when-not to use this tool.

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 a destructive, non-idempotent mutation; the description adds far more: replacements apply atomically, `old_str` must match exactly once, empty `new_str` deletes, ambiguity must be surfaced to the user rather than auto-resolved, headings have title/tile/H1/H2 semantics, and certain elements (file blocks, dividers, link styles, column types) are preserved. This is substantial disclosure beyond the structured hints.

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

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

Front-loads the mechanism and workflow before the detailed rules, and almost every sentence encodes a distinct constraint. It is long and leans on all-caps emphasis, but the complexity of the patch semantics justifies most of the length.

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

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

For a destructive, non-idempotent patch tool with an output schema, all the critical caveats are covered: matching rules, deletion semantics, heading restrictions, element-level editability, and the return/error contract. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: one `old_str` may span several blocks and cross tile headings, may cover only part of a block with the rest preserved, and supports reordering, merging, and splitting. That materially expands how `old_str`/`new_str` are understood.

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 first sentence states an exact verb and mechanism — 'Edit a page in place by search-and-replace over the markdown' — and names the sibling that produces the input (`xtiles_get_view_content`). An agent can distinguish this from a full-document update or a read 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 three-step workflow (read, copy exact substring, send replacements) and clear when-not conditions: collection/database pages cannot be patched at all and must go through the collection API, and tables cannot become non-table content — delete and add instead. Alternatives are named, not inferred.

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, so the safety profile is covered. The description adds genuinely useful detail beyond that: exactly what state is destroyed (color and color_size), what is preserved (icon, custom workspace color), and that the full tile-style state is returned. Auth requirements and rate limits are still unmentioned.

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 action and target are front-loaded, followed by the exclusion clause and the return 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 destructive mutation tool with full annotation coverage and an output schema, the description supplies everything an agent needs: the exact field set affected, the preserved state, and confirmation that resulting state is returned. 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 description coverage is 100%, with viewId documented including URL extraction and ID discovery, and tile_ids documented including its source (tile_id from xtiles_get_tile_styles). The description's mention of color/color_size clarifies the effect rather than the parameters themselves, so it does not go meaningfully 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 (clear) plus the exact resource scope (palette color of listed tiles on a page/view) and names the affected fields. It also enumerates what is NOT touched (icon, custom workspace color), which cleanly separates it from xtiles_set_tile_styles and xtiles_get_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?

The scope statement ('this manages only the palette color', icon and custom workspace color unchanged) gives clear context for when this tool is the right one rather than set_tile_styles. It stops short of explicitly naming the alternative tool or stating when-not-to-use, so it is clear but not fully routable.

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 declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds value beyond these by spelling out what 'destructive' means here (empty string clears and hides the description) and its UI placement under the page title.

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 compact sentences with the core action front-loaded. There is mild redundancy where the Markdown/empty-string details repeat the schema, but nothing is padded.

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 an output schema, the description covers purpose, set/clear behavior, and the return value. It is essentially complete, with only the absence of alternative-tool routing as a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in full (viewId URL extraction, Markdown format, empty-string clearing). The description's parameter notes largely duplicate the schema rather than adding new semantics, 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: 'Set (or clear) the description of an xTiles view (page) by viewId.' The narrow scope makes it distinguishable from broad siblings like xtiles_update_page or xtiles_patch_view_content, though no sibling is named explicitly to sharpen the contrast.

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 usage conditions: provide text to set and show, pass an empty string to clear and hide. It lacks explicit when-not or alternative-tool routing (e.g., vs xtiles_update_page), but the set-vs-clear context is well conveyed.

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 the useful partial-update contract and the personal-vs-project scoping rule, but says nothing about side effects of a destructive update (e.g. assignee replacement, completion cascades) that would justify the destructive flag.

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

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

Three short sentences, zero filler, with the core action and the partial-update guarantee front-loaded before the scoping detail. Appropriately sized for a tool whose parameters are fully documented in the schema.

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 no explanation, and the 100%-covered parameter schema handles field-level detail. The description supplies the two things the schema can't: partial-update semantics and the personal-vs-project targeting rule. Minor gap on side effects of the destructive semantics.

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

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

Schema description coverage is 100% across 8 parameters, so the schema already documents due-date formats, assignee replacement, Markdown descriptions and the projectId fallback. The description duplicates the projectId guidance rather than adding new semantics; 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?

Specific verb + resource ("Update an existing task"), clearly distinguished from sibling mutators like xtiles_create_tasks and xtiles_delete_tasks by the 'update' verb. It does not explicitly name or contrast a sibling, but the purpose is unambiguous.

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

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

Gives explicit conditional guidance on the key routing decision: supply projectId for project tasks, omit it for personal tasks. It also clarifies the partial-update mode ('Only specified fields will be updated'), so the agent knows this is a patch, not a replace. No alternatives or exclusions beyond that.

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