ctlsurf

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the mutation ('Add an item') and does not mention whether the item is appended, whether 'done' defaults to false, prerequisites like an existing checklist block, or any side effects.

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

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

The description is a single clear sentence with no filler and the action is front-loaded. It is concise, though slightly minimal; it could include more context without becoming bloated.

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 mutation with full schema coverage and no output schema, the description is adequate but incomplete. It does not mention preconditions (e.g., the block must be a checklist) or what the tool returns, which an agent might need 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 input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds no additional meaning beyond the schema, but the schema already documents block_id, text, and done adequately.

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 ('Add') and resource ('item to a checklist block'), which clearly distinguishes it from update_checklist_item. It does not explicitly name sibling tools, but the action is unambiguous enough for an agent to understand what the tool does.

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

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

There is no guidance on when to use this tool versus alternatives like add_ctlsurf_task_item or update_checklist_item. The agent must infer usage entirely from the name and description, with no exclusions or context provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that a task is added; it does not mention whether the block_id must already exist, whether duplicates are allowed, if the operation is reversible, or what the response contains. This is a significant gap for a 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 concise and front-loaded with the core purpose, followed by two helpful examples. It is efficient with no filler, though the examples are somewhat repetitive.

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 creation tool, the description covers the primary usage pattern. However, with no output schema and no annotations, it leaves out return values, prerequisites, and error behavior, which an agent might need to call the tool correctly in a complex workflow.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of value through examples showing block_id, text, and skill_id usage, but it does not introduce any parameter semantics beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Add a new task to a ctlsurf_task block') and clarifies the intended use ('create work items for yourself'). It is clear and unambiguous, though it does not explicitly differentiate from sibling tools like update_ctlsurf_task_item or add_checklist_item.

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 create work items for yourself' provides implied usage context. It gives no exclusions or guidance on when to prefer sibling tools such as update_ctlsurf_task_item for modifying existing tasks, so the guidance is minimal but not absent.

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?

With no annotations, the description carries the burden. It discloses two key behaviors (hidden, quota-free) but omits other important traits like reversibility (implied by restore_folder) and the effect on the folder's contents. This is useful but incomplete, so a 3 is appropriate.

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

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

Two sentences with zero fluff. The primary action is front-loaded, and the behavioral consequences are stated compactly. Every word earns its place.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers the core purpose and key behaviors but misses details such as whether the action is reversible (likely via restore_folder), permission requirements, or the effect on nested items. These gaps prevent a higher score.

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

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

The schema already fully documents the single parameter (folder_id as 'The UUID of the folder to archive') with 100% coverage. The description adds no parameter-specific detail, so it meets the baseline of 3 without exceeding 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?

The description states a specific verb ('Archive') and resource ('folder'), and immediately distinguishes the action from destructive alternatives like delete_folder by noting archived folders are hidden and don't count toward quota. This clearly differentiates it from siblings such as restore_folder or delete_folder.

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

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

The description provides clear context (hidden by default, quota exemption) that implies when to use it, but it does not explicitly name alternatives or state when not to use it. Since the intended use is inferable from the behavioral cues, this is a solid 4.

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?

With no annotations, the description carries the full burden and does well: it discloses that nothing is deleted, that the group's dashboard remains readable, and that restore_group reverses the action. It omits permissions/authorization needs, but the reversibility profile is the key unknown for an archive mutation and it is covered.

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 sentences, front-loaded with the action and scope before the safety caveat. The final confirmation directive earns its place; no wasted text.

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 mutation with no output schema and no annotations, the description covers action, scope, non-destructiveness, and reversal. Only auth/permission context is missing, which is a minor gap at this complexity.

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% with an example value ('SR GRP') already provided. The description adds no syntax or format 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 ('Archive a whole folder group') and clarifies the bulk scope ('every active project in it is archived at once'), which separates it from the sibling archive_folder (single folder). An agent can pick it 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 a caution ('Confirm with the user first') and names restore_group as the inverse operation, but never states when to prefer this over archive_folder or restore_group, nor any precondition. Usage is implied rather than 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?

With no annotations, the description must carry the burden of behavioral disclosure. It states the two main actions: verifying file existence and creating a file block. This is transparent about the core mutation. However, it does not disclose failure behavior (e.g., what happens if the file doesn't exist), idempotency, or whether it returns any value. These gaps leave some behavioral ambiguity, but the description is not misleading.

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

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

The description is two sentences with no fluff. The first sentence states the purpose, and the second gives a clear usage instruction and additional action. It is front-loaded and efficient, earning every word.

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

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

The description covers the key aspects: when to call and what it does. However, it lacks information about return values (no output schema) and potential failure conditions. For a tool that performs a verification step, the agent might need to know what happens on success or failure, but this is not provided. Given the simplicity of the operation and the explicit flow reference, it is moderately complete.

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

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

Schema coverage is 100%, so all six parameters are already described in the schema. The description adds contextual value by linking s3_key and file_id to get_upload_url, but this is also mentioned in the schema descriptions. It doesn't add new meaning beyond reinforcing the relationship, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: confirming a completed file upload and creating a database record/file block. It specifies the verb 'confirm' and the resource 'completed file upload', and distinguishes it from siblings like get_upload_url by referencing the presigned URL step. It doesn't explicitly contrast with create_block, but the phrase 'file block' makes the specialization clear, so it's a specific action.

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 explicit when-to-use guidance: 'Call this after successfully uploading a file to the presigned URL from get_upload_url.' This sets a clear precondition and implies not calling before upload. It doesn't mention alternatives, but the direct reference to the previous step in the flow is sufficient guidance for correct usage.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses several behavioral traits: react_flow auto-creates a Graph, markdown slide content renders as flat text, file upload through get_upload_url + confirm_upload creates the block, and dataspace blocks are restricted to dataspace pages. It stops short of describing return values, error conditions, or permissions, which is why it is not 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 description is long but front-loaded with purpose and organized by block type with consistent bullet formatting and code examples. Every section earns its place given 13 block types, but the overall length prevents a perfect conciseness score.

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

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

For a complex tool with no output schema and no annotations, the description covers all block types, their required props, constraints, and sibling-tool alternatives, which is enough to invoke correctly. The only notable omissions are return value and error behavior, which a brief addendum could close.

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?

Even though schema coverage is 100%, the props parameter remains a generic object and the description supplies the actual prop structures for every block type, with examples for nested mindmap and JSON tree formats. This meaningfully exceeds the schema's enum descriptions and is essential for correct invocation.

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

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

The description opens with 'Create a new block on a page,' naming the exact verb and resource, then enumerates all supported block types. It distinguishes the tool from siblings by noting which tools handle checklist item mutation, uploads, dataspace blocks, and presentations.

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

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

It gives explicit routing guidance: use add_checklist_item/add_ctlsurf_task_item after creation, use create_datastore/get_state/set_state/append_log/query_log for dataspace-only types, and use create_presentation for slide decks. It also states the dataspace-page-only restriction and the recommendation to prefer checklist for simple tasks versus ctlsurf_task for agent-assigned work.

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?

No annotations are present, so the description carries the burden. It discloses important non-obvious behavior: folder precedence, auto-creation of folders, and the fact that root pages with matching root_path or repo_url return an existing page instead of creating a duplicate. This goes well beyond the schema, though it does not cover auth or return format.

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 structured with a numbered precedence list and two illustrative examples. It is longer than a minimal definition, but each sentence adds behavioral value and the most important caveat is called out with 'IMPORTANT'.

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 8 parameters, no annotations, and no output schema, the description covers the non-obvious folder resolution and deduplication behavior that an agent must know to call the tool correctly. It does not describe return values or explicitly compare against sibling tools, but these are not critical to 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 adds significant meaning by explaining the precedence among folder_id, parent_id, and cwd, and by linking root_path/repo_url to the duplicate check. These relationships are not inferable from the individual parameter descriptions in 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 opens with 'Create a new page' and then details the specific behaviors of folder assignment and duplicate suppression. This clearly distinguishes the tool from siblings like create_block, create_page_link, update_page, and 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?

Provides concrete when-to-use context: creating a page with automatic folder resolution via folder_id, parent_id, or cwd, including auto-creation of folders. It also warns about the idempotent duplicate-return behavior. It does not explicitly name alternatives or exclusions, but the context is clear.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly indicates that the tool returns a formatted link string and does not imply persistent side effects. It also transparently notes the fallback behavior of using the page title if display_text is omitted, which implies a possible lookup operation. This is adequate for a utility-like tool, though it could explicitly state that no records are modified.

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 somewhat longer than necessary but every section serves a purpose: it states the purpose, explains the return format, gives an example, covers parameter fallback, and shows integration with another tool. It is front-loaded with the main objective and well-structured, though a shorter version could have been 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?

For a simple formatting tool, this is remarkably complete. It includes the return format, an example, parameter semantics, and a usage pattern in text blocks. It touches on fallback behavior and the rationale for using this tool (link validity). No critical information for an agent to call it correctly is missing, even without an output schema—the example return shape covers that.

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 value beyond the schema by showing a concrete example (page_id and display_text), explaining the fallback when display_text is missing, and illustrating how the return value is used in a block update. This enriches parameter meaning without redundancy.

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

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

The description clearly states a specific verb and resource: 'Create a properly formatted page link for use in markdown content.' It distinguishes itself from siblings like create_page (which creates a page) and find_linkable_pages (which finds pages) by focusing on link formatting. The example and explicit return format remove any ambiguity about the tool's role.

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 explicitly says 'Use this to generate links when creating or updating text blocks' and provides a concrete usage example with update_block. This gives clear when-to-use guidance and enough context to avoid misuse. Although it does not state when not to use it, there are no obvious alternative tools for this specific task, so the guidance is sufficient.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a key dependency (must call load_toolset first) and clarifies the invocation mechanism, but it does not mention error behavior, return format, or that side effects are entirely dependent on the invoked tool. While the dependency note adds some value, significant behavioral detail remains undisclosed.

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 concise, at two sentences, with the core purpose in the first sentence and usage guidance in the second. It front-loads the primary action and avoids any redundant or tangential content, making it easy to parse quickly.

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

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

Given that this is a dispatcher tool with only two parameters, no output schema, and no annotations, the description covers the essential workflow (call load_toolset first, then invoke by name and arguments) and the preference, which is sufficient for correct usage. It could mention return value or error handling, but since those depend on the invoked tool, the description is reasonably complete for its simplicity.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds minimal parameter-specific semantics; it repeats that you 'pass its name and arguments here' and references load_toolset for schema details, but this is more workflow than added meaning for the parameters themselves.

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

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

The description clearly states the tool's purpose: it invokes a ctlsurf tool from a deferred toolset by name. It distinguishes itself from direct calls by specifying that it's for deferred toolsets and notes that listed tools can also be invoked but direct calls are preferred. This is a specific verb-resource pairing with clear differentiation from siblings like load_toolset and the individual tool invocations.

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 explicit usage guidance: 'Use load_toolset first to get the tool's documentation and input schema, then pass its name and arguments here.' It also provides a clear exclusion: 'Listed tools can also be invoked this way, but calling them directly is preferred,' telling the agent when not to use this tool and to prefer direct calls for already-listed tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete' implies mutation/destruction, but the description does not state whether the deletion is reversible, whether it affects child blocks or references, or what permissions are required.

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

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

The description is a single concise sentence with no wasted words. The action and target are front-loaded, making it immediately scannable.

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

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

Although the tool is simple, it is destructive and has no output schema or annotations. The description leaves open important details like irreversibility, return behavior, and how to obtain the block_id, which an agent would need to call the tool safely and confidently.

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% for the single block_id parameter, so the schema already documents the only input. The description adds no parameter-level detail, but none is strictly necessary for a one-parameter tool with a fully described schema.

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

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

The description uses a specific verb ('Delete') and a specific resource ('a block from a page'), making the operation unambiguous. It clearly differentiates this tool from sibling delete_folder and delete_page tools, so an agent can tell them apart.

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

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

No guidance is provided about when to use this tool versus alternatives such as create_block, update_block, or restore_block_version. There is also no mention of prerequisites, such as how to obtain a valid block_id or whether deletion is soft or permanent.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the side effect that pages in the folder are moved to root level, but it does not disclose whether the folder deletion is destructive/permanent, whether confirmation or special permissions are required, or what the result of the operation is.

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 brief sentences with no filler. The primary action is front-loaded and the important side effect is stated immediately, making the description easy to parse quickly.

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

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

For a simple one-parameter destructive operation, the description explains the main action and one important consequence. However, it omits whether deletion is permanent or recoverable, what happens to subfolders or other contents, and any permission/restoration considerations, which an agent would benefit from knowing before invoking a destructive 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 coverage is 100%, so folder_id is already well documented as 'The UUID of the folder to delete'. The description adds no extra parameter-level meaning, but none is really needed given the single obvious parameter; 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 ('Delete') and resource ('a folder') and adds the key consequence that pages move to root level. This clearly distinguishes it from sibling tools like archive_folder and delete_page, so an agent can tell what operation this performs.

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 says what the tool does but gives no guidance on when to choose it over alternatives such as archive_folder or restore_folder. It does not state whether deletion is permanent, reversible, or how it relates to the trash/restore workflow, leaving the agent to infer the appropriate context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the cascade effect on blocks but omits whether deletion is reversible, whether the page moves to trash, what permissions are required, or how this differs from permanent_delete_page.

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

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

A single sentence with no filler or redundancy. Every word contributes meaning: the action, the target resource, and the cascade scope.

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?

Adequate for a one-parameter destructive operation with full schema coverage, but it leaves important gaps: no mention of return values, reversibility, trash behavior, or the distinction from permanent_delete_page. For a destructive tool with no annotations, this is a minimum-viable description.

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

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

The schema already fully documents page_id as 'The UUID of the page to delete,' with 100% schema description coverage. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Delete a page and all its blocks.' It clearly distinguishes this from delete_block (block-level deletion) and permanent_delete_page (permanent deletion), making the tool's scope immediately understandable.

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

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

No guidance is provided about when to use delete_page versus alternatives like archive_folder or permanent_delete_page. The existence of permanent_delete_page as a sibling suggests a soft-delete vs permanent-delete distinction that the description does not address.

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?

No annotations are provided, so the description must carry the behavioral burden. It only says 'find', implying a read operation, but does not disclose whether the path must be exact, whether multiple folders can match, what happens when no folder is found, or what the return value looks like.

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

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

The description is a single clear sentence with no filler or repetition. It is appropriately sized for a simple lookup tool, though it could have included more behavioral context without becoming bloated.

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

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

For a one-parameter lookup without annotations or output schema, this is minimally adequate: the agent knows what to search by and what resource will be returned. However, missing return/error semantics and match-behavior details leave some ambiguity.

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 root_path. The description adds no meaning beyond the schema; it restates the parameter's role. 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 ('find'), a specific resource ('folder'), and a precise lookup criterion ('codebase root path'). It clearly distinguishes this tool from the sibling find_page_by_root_path and from generic search/get 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?

The description implies this tool is for locating a folder by its exact root path, which gives some usage context. However, it does not explicitly state when to prefer it over alternatives like search_folder or get_folder, nor does it mention any exclusions.

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

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

With no annotations provided, the description must carry the full behavioral burden. It states that the tool 'Returns pages matching the search query with their IDs,' which covers the output. It also gives examples showing different parameter combinations. However, it does not disclose whether the operation is read-only (which is likely given the 'search' verb), whether there are any side effects, or how results are ordered. It also does not mention behavior when no parameters are given. The description adds some behavioral context but leaves gaps, so a 3 is appropriate.

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

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

The description is concise and well-structured. It opens with the tool's purpose in the first sentence, then gives usage guidance, followed by concrete examples. There is minimal redundancy, and the examples are illustrative without being verbose. It is not maximally tight (e.g., 'Search for pages to link to' and 'Use this before creating links' are slightly repetitive), but it is efficient and front-loaded with the core information.

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

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

For a tool with three optional parameters and no output schema, the description adequately conveys what it returns (pages with IDs) and how to use it. It does not, however, specify the response format in detail (e.g., whether it returns a list, what fields are included beyond IDs), nor does it explain behavior when no parameters are supplied or how query and folder_id interact when combined. Since there is no output schema, the description could do more to clarify the return structure, but the essentials are present. A 3 reflects that it is sufficient for basic usage but not fully complete.

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

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

The input schema covers all three parameters (limit, query, folder_id) with descriptions, giving 100% coverage. The description adds value by providing examples that clarify how the parameters are used (e.g., 'query' does a title search, 'folder_id' lists pages in a folder, 'limit' caps results). Since the schema already documents the parameters, the baseline is 3; the description reinforces their meaning but does not add significantly new semantics beyond the examples.

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

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

The description clearly states the tool's function: 'Search for pages to link to.' It specifies the resource (pages) and the purpose (to link), and mentions that it returns IDs for use with create_page_link. However, it does not explicitly differentiate from sibling tools like search_pages, which might also return pages. The purpose is clear enough for most agents to understand what it does, but the lack of explicit distinction from search_pages keeps it from a 5.

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

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

The description gives explicit usage context: 'Use this before creating links to find the right page.' This tells the agent when to use the tool. It does not mention when not to use it or name alternative tools, such as search_pages, which could be used for general page search. The guidance is clear for the primary use case but lacks exclusions or alternatives, so it's a 4 rather than 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?

With no annotations, the description carries the behavioral burden. It discloses the return shape ('match_type: repo_match/exact/parent'), ordering preference, and that root_path auto-detects the repo URL. It does not state behavior on no match or auth requirements, but 'find' implies a read-only operation.

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 sections: purpose, examples, and return semantics. It is front-loaded with the core use case and contains no filler; 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?

Covers purpose, parameters, and return semantics well, but does not state that at least one of repo_url/root_path is needed (schema marks both optional) or what happens when no match is found. This is a meaningful gap for a lookup 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 coverage is 100% and already notes 'preferred' and 'auto-detected'. The description adds concrete call examples and the 'cross-machine' rationale, which reinforces usage but only modestly extends what the schema already provides.

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

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

The description names a specific resource ('control plane page for a codebase') and a concrete use case ('locate your project's page on session start'). It is clear and distinct from sibling search/get tools by root-path/repo lookup, though it does not explicitly name a sibling 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?

Explicitly states when to use it ('on session start') and gives two parameter modes with a preference for repo_url. It does not mention when not to use it or alternatives like search_pages, so it stops short of a full 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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose the returned fields and confirms the result is a list of pages containing the target as a link. However, it does not mention failure modes, empty results, pagination, ordering, or authorization requirements, leaving some behavioral ambiguity.

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 tightly written: a one-sentence purpose, a one-sentence output summary, a one-sentence use case, and a minimal example. Every element earns its place and the most important information is front-loaded.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers the main things an agent needs: what it returns, what the parameter is, and an example. It does not describe edge cases like no backlinks or malformed IDs, but the tool is simple enough that this is 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% and the schema already explains page_id as the UUID of the target page. The description adds only an example call and clarifies the link direction, which is helpful but not a significant semantic improvement over 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 action and resource: 'Get all pages that link to a specific page.' This clearly distinguishes it from sibling tools like get_outlinks by specifying the direction of the relation.

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

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

It explicitly says to use this to 'understand how pages are connected and discover related content,' which is clear context for when it should be used. It does not name alternatives or exclusion conditions, but the usage intent is clearly 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?

With no annotations, the description carries the behavioral burden. It correctly conveys that the tool retrieves historical versions rather than mutating the block, and it notes that versions are restorable. However, it does not disclose output shape, ordering, pagination, 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 short sentences with no filler. The primary action is front-loaded, and the second sentence adds relevant behavioral context about restorability.

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 low-complexity, one-parameter retrieval tool, the description is largely sufficient. It states the resource and the nature of the result. The absence of an output schema means some return-format detail is missing, but the description's basic statement of what it shows is enough for correct invocation.

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

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

Schema description coverage is 100% and the single parameter block_id is already documented as 'The UUID of the block.' The tool description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get version history for a block.' It clearly states what is returned (previous versions) and the fact that these versions are restorable, which distinguishes it from sibling restore 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?

The context is clear: use this tool when you need a block's version history. The phrase 'that can be restored' implies a connection to restoration, but the description does not explicitly name restore_block_version as the alternative for performing the restore.

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?

No annotations are present, so the description carries the behavioral burden. It does disclose that this is a fetch operation and that paging metadata is returned, but it does not specify the shape of that metadata, the terminal pagination condition, or behavior for invalid or missing block IDs.

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

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

Two sentences with no filler. The core action is front-loaded, and the pagination guidance follows immediately.

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

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

For a simple three-parameter read tool without annotations or an output schema, the description supplies purpose, pagination strategy, and the existence of paging metadata. It stops short of documenting the paging metadata fields or the end-of-pagination signal, which would make it fully self-contained.

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 block_id, offset, and limit with defaults. The description reinforces the offset/limit pagination usage but adds no information beyond what the schema provides.

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

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

States a specific action and resource: fetch a slice of a block's content. The qualifier 'for large blocks' and the focus on pagination distinguish it from list_blocks or get_block_history without ambiguity.

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?

Clearly explains how to use offset/limit to paginate and signals that the tool is intended for large blocks. It does not name an alternative tool or give an explicit when-not-to-use condition, so it falls slightly short of full usage 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?

With no annotations, the description carries the full behavioral burden. It explains that the tool returns instructions to add to a config file, lists the content returned, and gives the required preparation steps. It does not explicitly state that the tool avoids modifying the project, but the return-value framing makes that reasonably clear.

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 longer than necessary but well-structured with a summary, trigger, usage steps, and examples. The front-loaded first sentence immediately conveys the tool's purpose, and the bullet list is scannable.

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

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

The description is self-contained: it gives trigger phrases, parameter discovery commands, call examples, and a detailed list of what the returned instructions cover. Even without an output schema, an agent has enough information to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by showing realistic examples and clarifying that root_path, repo_url, and hostname are all expected when calling the tool, even though only root_path is required by 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 clearly identifies the tool's purpose: get ctlsurf integration instructions or initialize a project for ctlsurf. It is distinct from all sibling tools, which focus on pages, blocks, folders, and tasks.

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 explicitly states when to use the tool with trigger phrases and provides a clear step-by-step usage workflow. It does not mention when not to use it or compare with an alternative, but no sibling tool appears to fill the same role.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It correctly indicates the operation is a read and that only text-based files are supported, but it does not mention error behavior for non-text files, encoding, size limits, or return format specifics. This is acceptable but minimal for a simple getter.

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

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

A single clear sentence that front-loads the action and object. Every word contributes meaning, and the parenthetical examples add useful scope without bloat.

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

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

For a one-parameter read-only tool with no output schema, the description is nearly complete: it states the action, the target file type, and examples. It could explicitly note what happens when a non-text file is requested, but the core calling context is adequately covered.

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 only parameter, file_id, is already documented as 'The UUID of the file'. The description adds no new semantic meaning 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?

The description specifies a clear verb ('Get'), a resource ('file'), and a precise scope ('text content from a text-based file'). This distinguishes it from siblings like get_image and get_image_url by limiting it to text-based formats.

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

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

The phrase 'text-based file (txt, md, json, etc.)' implies this tool is for text files and not for images or binary files, but it does not explicitly state when to use this tool versus an alternative or name any sibling tool. The usage context is therefore only implied.

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

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

No annotations are provided, so the description carries the behavioral burden. 'Get' implies a read operation, and 'with its pages' discloses that the response includes page content. It does not explain whether pages are full objects or summaries, nor what happens on a missing folder ID, but for a simple retrieval tool this is acceptable.

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 one short sentence with the action and scope front-loaded and zero filler. Every word earns its place.

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

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

For a one-parameter retrieval tool this is close to sufficient: it names the input and the expected result composition. However, with no output schema and no sibling-routing hints, an agent still lacks the exact response shape and alternatives, leaving clear but minor gaps.

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

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

The schema already documents folder_id fully as a required UUID with 100% description coverage. The description only echoes 'by ID' and adds no extra meaning about the parameter's format, source, or constraints, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('folder'), and adds the distinguishing lookup mechanism ('by ID') and the result content ('with its pages'). This lets an agent separate it from path-based lookup tools like find_folder_by_path and page-level tools like get_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?

The description implies when to use the tool: when the caller already has a folder ID and wants the folder along with its pages. However, it gives no explicit guidance about when to prefer it over sibling tools such as list_folders, get_page_tree, or find_folder_by_path, and it offers no exclusions.

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

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

With no annotations, the description carries the full burden and it does disclose meaningful behavior: the return shape is base64-encoded image plus metadata, and the operation sends full image data through MCP, which is expensive for large images. It does not mention auth, rate limits, or failure modes, but the cost/scale disclosure is valuable and beyond a simple 'get' statement.

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 purpose and return format, then the usage caveat and alternative are clearly separated. There is minor redundancy in saying 'base64 data' and then 'base64-encoded image', but every major sentence earns its place and the warning is well-positioned.

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

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

For a one-parameter read tool with no output schema and no annotations, the description covers the main things an agent needs: what it returns, when to use it, when not to use it, and the cost implication. It could mention metadata fields or size constraints, but it is not incomplete enough to warrant a lower score.

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%: the only parameter, file_id, is already documented as 'The UUID of the file to retrieve'. The description adds no new parameter-level meaning, but none is needed because the schema fully covers 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?

The description names a specific verb and resource ('Get an image as base64 data') and explicitly differentiates itself from the sibling get_image_url. An agent can immediately tell this is the vision-analysis variant, not the URL-returning variant.

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 states when to use the tool ('Only use this when you need to ANALYZE image content'), gives concrete examples, and explicitly routes all other cases to get_image_url. This is unambiguous guidance with a named 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?

No annotations are present, so the description carries the full behavioral burden. It discloses that the URL is temporary, valid for 1 hour, requires no authentication, and costs almost zero tokens, plus it gives practical usage examples. This is substantial, useful disclosure beyond the tool name and schema.

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

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

The description is front-loaded with the core purpose and key details, then uses concise bullet points for use cases, and ends with an explicit alternative. Every sentence adds value and the structure makes it easy to scan.

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 tool with no output schema, the description provides selection guidance, access semantics, expiration, cost, and rendering examples. An agent has everything needed to decide to use it and 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?

The schema already describes file_id as 'The UUID of the file' with 100% coverage, so the description adds little on parameter semantics. The description does reinforce that the tool works for images/files, but it doesn't add format, source, or usage details for the UUID beyond the schema. 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 action ('Get a temporary presigned URL') and resource ('image/file'), and explicitly distinguishes itself from the sibling get_image by noting that get_image is for vision analysis. The purpose is immediately clear and unambiguous.

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

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

Explicitly positions this tool as the DEFAULT way to access images, lists concrete use cases, and gives an explicit when-not: 'Only use get_image instead when you need to ANALYZE image content with vision.' This is ideal routing guidance for an agent.

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?

With no annotations provided, the description carries the full burden. It honestly describes the return data and gives an example, but it does not explicitly state that the operation is read-only, mention ordering, pagination, error behavior, or permissions. For a simple getter this is adequate but not rich.

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 compact and well-structured: purpose, return shape, and a concrete example. Every sentence adds value and the example is front-loaded after the purpose statement, avoiding 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 tool's simplicity, one required parameter, and no output schema, the description provides enough context for correct invocation: what it does, what the parameter is, and what the return contains. Minor gaps like pagination or failure modes do not undermine usability for a basic read operation.

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

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

Schema coverage is 100% and the single parameter is already described as the UUID of the source page. The description's example reinforces this but adds no deeper semantic detail beyond the schema, 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 states a specific verb and resource ('Get all pages that a specific page links to') and clarifies the output fields (target page title, block ID, link text). This clearly distinguishes it from get_backlinks, which would cover incoming links, so an agent can tell them apart 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?

The tool's use case is clear from the description and example, and the term 'links to' implies outgoing links rather than backlinks. However, it does not explicitly mention when to prefer this over get_backlinks or provide an exclusion, so it stops short of the best-practice guidance 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?

With no annotations, the description must carry the behavioral burden. 'Get' and 'including all its blocks' communicate a read operation and the main payload, but the description does not explain response shape, whether blocks are returned flat or recursively/nested, error behavior for missing IDs, or size/pagination implications. These are meaningful gaps for a tool with no output schema.

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

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

The entire description is one front-loaded sentence with no filler. Every clause contributes: the operation, the identifying key, and the return scope.

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-only tool, the description contains the core facts needed to select and invoke it: it targets a page by ID and returns the page's blocks. The lack of an output schema makes some return-shape ambiguity unavoidable, but 'including all its blocks' sets the right expectation; the main omission is explicit routing to sibling tools, which is already penalized under usage guidelines.

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 defines page_id as 'The UUID of the page,' so the description need not repeat it. The phrase 'by ID' merely reinforces the schema and adds no new format, constraints, or relationship guidance.

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

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

The description uses a concrete verb and resource: 'Get a specific page by ID' and immediately scopes the output to 'all its blocks.' This lets an agent distinguish it from sibling tools like get_page_summary and get_page_tree, which imply summary or hierarchy rather than full block 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?

The description implies the right context—use when you already have a page UUID and need the page's block content—but it never states when to prefer it over get_page_summary, get_page_tree, or search_pages, nor does it give exclusions. Without explicit alternative routing, the agent must infer intent from the name and the phrase 'by ID.'

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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the resource and return fields; it does not explicitly confirm read-only behavior, mention error cases (e.g., missing page), authorization needs, or any side effects. 'Get' implies a read operation, but that is not stated.

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

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

Two short sentences with no filler. The first front-loads the verb and resource; the second lists the return contents, which is useful and directly 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?

For a one-parameter read tool, the description is moderately complete: it states the resource and output fields, which partially compensates for the missing output schema. However, it lacks alternative-selection guidance and behavioral caveats, so an agent may not know when to choose this over get_page or what happens for invalid/nonexistent pages.

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

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

The input schema already fully describes page_id as a UUID string with 100% coverage. The description adds little beyond 'for a page,' so parameter semantics remain at the baseline for fully covered schemas.

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

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

The description uses a specific verb and resource ('Get the page summary block for a page') and lists the returned fields (summary, purpose, status, tags, key topics). It is clearly distinguishable from siblings like get_page, which would return more page data, and update_page_summary, which is the 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?

The description gives no explicit when-to-use or when-not-to-use guidance. It does not differentiate from closely related tools such as get_page, get_page_tree, or search_pages, leaving the agent to infer when this tool is preferable.

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?

No annotations are provided, so the description carries the behavioral burden. It communicates a read-style operation via 'Get' and the returned concept (tree structure), but it does not mention output size, pagination, or whether page content/metadata is included. For a simple no-parameter read this is adequate but minimal.

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

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

The description is a single, front-loaded sentence with no filler. It states the resource and scope efficiently, earning its place.

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

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

For a zero-parameter tool the description names the output concept well, but with no output schema and no annotations it leaves the exact shape of the tree undefined (parent/child fields, whether it's the full workspace, size). The description is probably callable but not fully complete for an agent needing to interpret results.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter semantics to explain; per the baseline for 0-param tools this is strong. The description correctly avoids inventing parameter details.

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 (Get), resource (hierarchical tree structure), and scope (all pages), making the tool's purpose immediately clear. It distinguishes this from sibling tools like get_page (single page) and list_pages (flat list) by explicitly saying 'tree structure'.

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

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

The phrase 'hierarchical tree structure of all pages' implies use when the full page hierarchy is needed, but it provides no explicit when-to-use vs alternatives such as list_pages, search_pages, or get_page. There are no exclusion statements, so the agent must infer the right choice from the tool name and sibling context.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clarifies that only pending tasks assigned to the agent are returned, and it notes that tasks may include a skill (playbook) with workflow steps and guards. The verb 'Get' implies a read-only operation, and no destructive or state-changing behavior is suggested. It could be more explicit about side effects or return structure, but for a retrieval tool this is reasonably transparent.

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 purpose and then provides three concise, useful examples plus a note about skills. It is slightly longer than strictly necessary because the examples partly repeat schema descriptions, but each example adds a distinct usage pattern and the structure is easy to scan.

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 simple optional-parameter interface and no output schema, the description covers the main invocation modes and hints at what returned tasks may contain. It does not fully describe the task item structure or return format, but the examples and the skill note give an agent enough context to call the tool correctly.

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

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

The input schema already documents both parameters well (100% coverage), so the baseline is 3. The description adds value by showing concrete invocation examples, marking repo_url as preferred, explaining that root_path auto-detects the repo URL, and documenting the no-argument behavior of returning all pending tasks across projects. This goes beyond the schema 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?

The description states a specific verb ('Get'), a specific resource ('pending ctlsurf_task items assigned to you'), and a clear scope. It is immediately distinguishable from sibling tools like add_ctlsurf_task_item and update_ctlsurf_task_item, which are mutations, and from get_ctlsurf_instructions, which retrieves instructions rather than tasks.

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 explicitly says to call this on session start to check for work, which gives clear timing guidance. It also provides three usage examples covering repo_url, root_path, and no-argument invocation. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to decide.

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?

No annotations are present, so the description bears the full burden. It discloses the return payload, the 15-minute URL expiry, supported MIME types, and the required follow-up step (confirm_upload), which is substantial behavioral detail. It does not cover failure modes or permission requirements, but those are secondary for this 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 purpose is stated in the first sentence, followed by a compact numbered flow and constraint notes. No sentence is filler; even the curl example and expiry are 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?

For a tool with no output schema and no annotations, the description fully covers inputs, outputs, the required follow-up, expiry, and type restrictions. An agent has everything needed to call it and complete the upload workflow.

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

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

The schema already documents all three parameters with examples (100% coverage), so the baseline is 3. The description adds value by constraining mime_type to supported types (png, jpg, gif, webp, PDFs, Office docs) and by showing exactly how filename and mime_type are used in the curl invocation.

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 outcome—obtaining a presigned URL for direct file upload—and distinguishes itself from confirm_upload by framing this as phase 1 of a three-step upload flow. The resource (file upload) and key return values (upload_url, file_id, s3_key) are 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?

The description gives clear context: use when uploading file data without sending it through MCP, and pairs it with Bash curl and confirm_upload as the follow-up. It does not explicitly name the alternative upload path or state when not to use it, so it falls short of a full when/when-not specification.

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?

With no annotations, the description carries the full behavioral burden, but it only states that blocks are listed. It does not disclose whether results are paginated, sorted, or limited to direct blocks versus nested/child blocks, so the agent lacks important context about what the call actually returns.

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

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

A single, front-loaded sentence with no filler. Every word contributes meaning, and the key resource and scope are immediately clear.

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

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

The tool is simple, with one well-documented parameter and no output schema required to justify a plain listing behavior. The description is adequate for basic invocation, though richer detail about pagination or scope could push it higher.

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 there is only one parameter, page_id, whose meaning is already documented as 'The UUID of the page.' The description's phrase 'for a specific page' adds little beyond the schema, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource ('List all blocks for a specific page') and clearly states the scope. However, it does not differentiate from the sibling list_blocks_meta or search_blocks, so an agent could be unsure which block-listing tool to pick.

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 condition 'for a specific page' implies when the tool is appropriate, but no alternatives or exclusions are mentioned. An agent gets only implicit usage guidance, with no routing among the many block-related siblings.

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

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

No annotations are provided, so the description carries the full burden. It discloses that this returns lightweight metadata only, excludes props, includes size hints, and avoids pulling full content. This meaningfully describes behavior, though it does not detail pagination, ordering, or exact 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?

Two short sentences deliver the key facts with no filler. The core purpose is front-loaded, and the use-case guidance is placed immediately after.

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

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

For a simple one-parameter list operation, the description is largely complete: it states what is returned and why to use it. However, with no output schema and no annotations, some specifics about the returned metadata fields or limits are left unspecified.

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

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

The input schema covers 100% of the single parameter with a clear description ('The UUID of the page'). The tool description does not add parameter-level detail, but the schema already provides sufficient meaning, 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?

The description uses a specific verb ('List') and a precise resource ('lightweight block metadata (no props) for a page, including size hints'). It clearly differentiates from the sibling list_blocks by noting that it excludes props and does not pull full 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?

The phrase 'Use this to discover blocks without pulling full content' gives a clear intended use case and implies the alternative of fetching full content. It does not explicitly name sibling tools or state when not to use it, but the context is 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?

No annotations are provided, so the description carries the full burden. It discloses the default return behavior (metadata only), the effect of include_pages=true (nested page trees), and the size warning. It does not mention include_archived behavior, ordering, or auth, but the core behavioral traits of a list operation are covered.

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 concise sentences with no wasted words. The primary action and default behavior are front-loaded, followed by parameter usage and an alternative. 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?

Given no output schema and no annotations, the description covers the main use cases: default listing, optional page trees with size warning, and the pointer to get_folder. It could mention archived folder defaults, but the schema covers include_archived. Overall quite complete for a list 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 baseline is 3. The description adds a little extra meaning by clarifying 'metadata only' and the size warning, but these mostly restate the schema. It doesn't add new information about include_archived. Adequate, not outstanding.

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

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

States a specific verb and resource: 'List all folders (codebase workspaces).' It clearly identifies what is returned by default and differentiates itself from get_folder by pointing to the alternative. The purpose is unmistakable and distinct from sibling 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?

Gives explicit when-to-use guidance: use include_pages=true for nested page trees, and 'prefer get_folder(folder_id) for a single folder's pages.' It also warns about very large responses, which helps the agent decide whether to set include_pages. This is model 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?

With no annotations provided, the description carries the full burden. It discloses the return format (metadata fields) and implies a read-only operation via the verb 'list'. It does not mention pagination or side effects, but for a simple list tool this is acceptable.

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: the first states the action and scope, the second lists the returned metadata. No filler words, and the key information is front-loaded.

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

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

For a tool with one parameter and no output schema, the description covers the essential purpose and return type. It does not explain how results are ordered or paginated, but such details are not critical for a basic listing operation.

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

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

The schema fully describes the only parameter (page_id as UUID). The description adds no extra meaning about the parameter itself, only about the operation, so it meets the baseline without improving 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?

The description clearly states the action (list), the resource (files/images attached to a page), and the output (metadata). It implicitly distinguishes from siblings like get_image or get_file_text by focusing on the listing behavior.

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 provides clear context for when to use the tool: when you need a list of attached files/images and their metadata. However, it does not mention alternative tools for specific file retrieval or any exclusions, so it misses explicit 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?

With no annotations, the description carries the behavioral disclosure burden. It does disclose key behavior: slim metadata is the default, folder_id filters results, and slim=false triggers full details. It does not mention pagination, result limits, ordering, or the exact shape of 'full page details,' which are relevant for a list endpoint without an output schema.

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

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

Three short sentences, front-loaded with the core action and default behavior. Every sentence adds information: what is listed, what the default returns, how to filter, and how to opt into the heavier response. No wasted words.

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

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

For a simple read-only listing tool with two optional parameters and no output schema, the description covers the default return fields and explains both parameters. It leaves some gaps—full-details response fields, pagination, and behavior when no folder_id is provided—but the essential invocation context is present.

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 meaning beyond the schema. It maps folder_id to 'project' semantics and warns that slim=false should be used 'only if' full details are needed. This gives an agent practical guidance on when and how to use each 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 opens with a specific verb and resource: 'List pages.' It further clarifies the default response shape (slim metadata with id, title, folder_id, parent_id, tags, type), which helps distinguish this bulk-listing tool from nearby siblings like search_pages or get_page. However, it does not explicitly name or contrast any sibling tool.

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

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

The description gives clear parameter-level guidance: 'Use folder_id to filter by project' and 'Use slim=false only if you need full page details.' This implies the tool's main use case but does not explain when to prefer list_pages over search_pages, find_page_by_root_path, or list_folders. There is no when-not-to-use or alternative routing.

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?

No annotations are provided, so the description carries the full burden of behavioral transparency. The verb 'List' communicates a read-only operation and the restoration note adds useful context, but the description does not mention pagination, ordering, or what fields are returned. It is honest but minimal.

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 the core purpose front-loaded in the first sentence and a relevant, non-redundant follow-up in the second. There is no padding or unnecessary detail.

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

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

For a zero-parameter, no-output-schema read tool, the description is nearly complete: it states the exact object (deleted pages) and the natural follow-up action (restoration). The only omissions are minor operational details like pagination or ordering, which are not strongly implied by 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?

The input schema has zero parameters and the description does not need to invent parameter-level detail. With no parameters to document, this is effectively a baseline-4 situation; the description correctly avoids irrelevant parameter content.

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

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

The description uses a specific verb ('List') and a specific resource ('all deleted pages in the trash'), distinguishing this tool from sibling list_pages, which presumably lists non-deleted pages. It clearly states what the tool does with no ambiguity.

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

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

The description implies when to use this tool (when you need to see deleted pages), but it does not explicitly name alternatives or state when not to use it. The note that deleted pages can be restored hints at a follow-up workflow but never points to restore_page or list_pages.

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?

With no annotations, the description carries the full burden and does disclose the key behavior: this is a two-step discovery step whose output must be invoked through ctlsurf_call, and it states what is returned (documentation plus input schemas). It does not say whether loading has side effects, is cached, or is idempotent, which is a minor remaining gap for a loader.

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 routing instruction, and the toolsets list earns its length because it is the only place the enum values are explained semantically. Minor redundancy in 'Call this when you need one of them' against the preceding sentence 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?

No output schema and no annotations, but the description compensates by explaining the discovery-then-invoke flow and summarizing what each toolset contains. It never shows the shape of the returned payload, which is the one thing an agent might still want before calling.

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 is self-documenting, so the baseline would be 3. The description goes beyond that by annotating each enum value with its tool count and content domain (e.g. 'dashboards (18 tools): group dashboards with change-order, proposal/SOW and ticket cards'), which genuinely helps the agent pick the right 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 ('Load the documentation and input schemas for a deferred toolset') and immediately explains the deferred-toolset mechanism that distinguishes it from the directly-listed sibling tools. An agent can tell exactly what it retrieves 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 an explicit trigger ('Call this when you need one of them') and an explicit follow-up ('then invoke the returned tools via ctlsurf_call(tool_name, arguments)'). It also explains why the toolsets are deferred, which is the condition under which this tool rather than a direct sibling call applies.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It does clearly disclose that the operation is destructive and irreversible ('This cannot be undone!'), which is the most critical behavioral fact. However, it does not explain side effects such as whether child pages or associated content are also destroyed, or whether the page must already be in trash.

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 words. The key warning 'cannot be undone' is placed immediately after the action, making the risk prominent and front-loaded.

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

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

The tool is simple, with one fully documented parameter and no output schema, so extensive context is not strictly required. Still, for a destructive irreversible action, the description could state what exactly is destroyed (e.g., children, attachments) and whether the page must be in trash first. The current description is minimally adequate but leaves these edge behaviors 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 the single page_id parameter already documented as 'The UUID of the page to permanently delete'. The description adds no additional parameter semantics, but the schema fully covers what is needed.

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 action ('permanently delete') on a specific resource ('a page'). The word 'permanently' clearly distinguishes it from the sibling delete_page, which likely performs a soft delete, and from archive_folder and restore_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?

The description gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like delete_page or warn that this should only be used after the page is already in trash. While 'permanently delete' implies a usage context, that is inferred rather than stated.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'restore' without describing side effects, whether the operation is destructive, if it creates a new version, or any permission requirements. This is insufficient for a 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 a single sentence with zero filler, front-loading the core action. It is appropriately concise for a simple tool, though it sacrifices detail for brevity.

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

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

For a mutation tool with no annotations and no output schema, the description is severely lacking. It does not explain the consequences of restoring (e.g., overwriting current content), whether it is reversible, or any constraints. An agent cannot fully anticipate the tool's behavior.

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

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

The schema already describes both parameters (block_id as UUID and version_number as the target version) with 100% coverage. The description adds no additional meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the verb 'restore' and the resource 'block to a previous version', which is specific and not a tautology. It distinguishes the action from related tools like get_block_history (which retrieves history) and restore_page/restore_folder (which restore different entities), though it does not explicitly name them.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, use cases, or contrast with restore_page or get_block_history. An agent must infer usage from the name and schema alone.

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

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

No annotations are provided, so the description carries the full burden. It clearly states the state change (archived → active), but does not disclose additional behavioral traits such as whether contents are restored, permissions required, or reversibility. The core behavior is transparent, but coverage is minimal.

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

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

One sentence, directly front-loaded with the action and resource, with no wasted words. It efficiently conveys the tool's purpose.

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

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

For a simple one-parameter tool, the description is almost complete: it states the operation, the input, and the desired state change. It could mention what happens to the folder's contents or require that the folder actually be archived, but these are minor gaps.

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

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

Schema description coverage is 100%, so the single parameter folder_id is already fully documented. The description adds no additional meaning beyond linking the parameter to the archived folder context, which is the expected 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?

The description uses a specific verb ('Restore') with a clear resource ('archived folder') and outcome ('back to active status'). It fully distinguishes this tool from sibling tools like restore_page and restore_block_version, which target different resources.

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

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

The description clearly implies when to use this tool: when a folder is archived and should become active again. It does not explicitly name alternatives or exclusions, but the archived-to-active framing provides enough context to select it correctly.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the operation restores all archived projects in a group and is the inverse of archive_group, but it does not cover permissions, side effects, idempotency, or what happens if some projects are already active.

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

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

One sentence, front-loaded with the main action and scope, with zero wasted words. The inverse relationship is included efficiently at the end.

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

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

For a simple one-parameter mutation tool with full schema coverage and no output schema, the description is nearly complete: it states the action, scope, and inverse sibling. It could add a note on permissions or failure behavior, but nothing essential for 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 single parameter 'group' is documented as 'The group name'. The description adds only the contextual phrase 'folder group', which aligns with the schema but does not introduce additional meaning. Baseline 3 is appropriate when the schema already 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 ('Restore') and resource ('every archived project in a folder group'), and explicitly names the inverse operation ('undoing archive_group'). This lets an agent distinguish it from restore_folder and restore_page 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?

The phrase 'undoing archive_group' gives clear context for when to use this tool: after archiving a group, call this to reverse it. It does not explicitly state when not to use it or name alternatives like restore_folder, but the use case is clear.

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?

No annotations are provided, so the description carries the full burden. It clearly conveys the core state transition (trash to restored), but does not disclose potential side effects such as child page restoration, idempotency, permission requirements, or what happens if the page is not in trash.

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

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

One clear, front-loaded sentence with no redundant content. Every word contributes to the understanding of the operation.

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 low-complexity tool with a single documented parameter and no output schema, the description is mostly sufficient. Minor gaps remain around edge cases and return behavior, but an agent can correctly identify and invoke the tool with the information provided.

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

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

The single parameter page_id is already fully described in the input schema ('The UUID of the deleted page'), with 100% schema coverage. The description adds no additional parameter context, so it meets the baseline but does not go 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?

The description uses a specific verb ('restore') and identifies both the resource ('deleted page') and the source state ('trash'). This clearly distinguishes it from siblings like restore_folder, restore_block_version, and permanent_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?

The intended use case is clear: restoring a page that has been deleted and is currently in trash. It does not explicitly mention alternatives, but the explicit page/trash context prevents confusion with restore_folder, restore_block_version, or permanent_delete_page.

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?

With no annotations, the description carries full behavioral burden. It does disclose that only snippets are returned and that full content requires another tool, which is useful. However, it does not mention read-only behavior, search scope, result formatting, pagination behavior, or any access 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 description is two short sentences with no filler. It front-loads the core purpose and then gives a clear pointer to the sibling tool for the next step.

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

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

With no output schema and no annotations, the description should say more about what a snippet looks like and what the response contains. It gives a solid high-level workflow but leaves the agent guessing about return structure, search scope, and edge cases.

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. The description adds only that searching targets 'block content' and returns 'snippets', which maps to the query parameter but does not meaningfully expand on limit, offset, or page_id semantics.

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

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

The description uses a specific verb ('Search'), a clear resource ('block content'), and states the output form ('return snippets'). This distinguishes it from sibling tools like search_pages or search_folder by explicitly scoping to block 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?

The description directly tells the agent what to do after finding matches: use get_block_slice for full content. This is explicit workflow routing and clearly separates the snippet-focused purpose of this tool from the full-content 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?

No annotations are present, so the description carries the full burden. It does disclose that the tool 'returns the matching folder(s) with match_type indicator' and notes 'partial match' for name queries, which is useful. However, it does not explicitly state that this is a read-only operation or mention any side effects, errors, or permissions, which would be expected for a search tool without annotation coverage.

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 description is a single clear sentence, followed by three bulleted examples that are front-loaded and easy to scan. Each sentence has a purpose, and there is no fluff. The structure makes it efficient for the agent to parse and apply.

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 search tool with no output schema, the description covers the essential details: purpose, query types, examples, and return information (match_type). It does not mention pagination or error conditions, but these are not critical given the tool's simplicity. The only notable gap is not referencing sibling alternatives for routing, which is a minor completeness issue.

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% with clear descriptions for both parameters. The description adds value by providing concrete examples for each type and clarifying that 'name' does partial matching. This goes beyond the schema's basic enum and value descriptions, helping the agent understand proper parameter combinations.

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

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

The description uses a specific verb ('Search') and resource ('folder'), and specifies three distinct search modes (path, git URL, name) with concrete examples. This clearly distinguishes it from sibling tools like search_blocks and search_pages, and even from find_folder_by_path by covering multiple types.

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

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

The description provides examples for each query type, which implicitly guides usage, but it does not explicitly state when to use this tool versus alternatives like find_folder_by_path or get_folder. No exclusion criteria or 'use this instead when...' guidance is given, so the agent must infer the context from sibling names.

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?

With no annotations, the description carries the burden and provides substantive behavior: stemming (run/running/ran) and typo tolerance threshold 0.3. It does not mention result ordering or read-only status, but the search semantics are unusually specific.

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

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

Two sentences with no filler; the core action is front-loaded and the matching specifics are provided compactly. Examples are illustrative rather than redundant.

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

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

For a four-parameter search tool with no annotations and no output schema, the description covers matching behavior but omits result shape, default sorting, and any distinction from sibling search tools. This is adequate for invocation but leaves selection and output expectations to inference.

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 fully documents limit, query, offset, and folder_id. The description adds title-scoped fuzzy semantics for query, but it does not need to compensate for missing schema 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?

The description states a specific verb ('Search') and resource ('pages by title') and specifies the matching mechanism (full-text with fuzzy matching). This clearly distinguishes it from siblings like search_blocks or list_pages.

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

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

The description gives no guidance on when to choose this tool over search_blocks, search_folder, or list_pages, and no exclusions or alternatives are named. The only implied context is that the target is pages searched by title.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates that the tool mutates a block but does not explain whether updates are partial or full replacements, whether order changes have side effects, what permissions are needed, or whether changes are reversible.

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

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

The description is a single, efficient sentence with no filler or irrelevant detail. The core operation and target fields are front-loaded, making it easy to scan.

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 no annotations and no output schema, this description is too thin. It omits update semantics, required identification context, potential failure modes, and any behavioral constraints beyond the bare operation.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter guidance. The description repeats the schema's own field names ('properties, title, or order') and adds no meaning about the nested 'props' object or valid values.

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: it updates a block's properties, title, or order. This is clear and distinguishable from create_block or delete_block, though it does not explicitly differentiate from restore_block_version or other update_* 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?

No guidance is given about when to use this tool versus alternatives, nor when not to use it. The description merely names the operation and fields, without mentioning exclusions, prerequisites, or the fact that create_block/restore_block_version serve different purposes.

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?

With no annotations, the description carries the full burden, but it only indicates a mutation without disclosing update semantics (partial vs full replacement), validation, required lookup keys, or what the response contains. No contradiction with annotations, but the description is too thin.

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 text is a single short sentence with no wasted words. It is front-loaded but arguably under-specified; the brevity does not substitute for the missing behavioral detail.

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 no annotations and no output schema, this description is incomplete: it does not explain that block_id and item_id identify the target, that done/text are the mutable fields, or that at least one update should be supplied. The schema fills parameter names but not behavioral context.

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

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

All four parameters are described in the input schema, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what the schema already provides, hence the baseline of 3.

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

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

The description states a clear verb ('Update') and a specific resource ('checklist item'), so an agent knows the basic operation. However, it does not differentiate this from siblings such as update_block or add_checklist_item, and gives no detail about which aspects can be changed.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention that it should be used for modifying an existing checklist item rather than creating one (add_checklist_item) or updating block-level properties (update_block).

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?

With no annotations, the description carries the behavioral burden. It discloses a crucial non-obvious invariant: done=true REQUIRES the structured completion object. It also clarifies reopen_feedback usage, skill attachment, and the difference between notes and completion. It stops short of describing permissions or persistence details, but the core side effects and constraints are visible.

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 longer than average, partly due to code examples, but every example earns its place by showing real call patterns and the completion schema. The summary line is front-loaded and the IMPORTANT note reinforces the critical constraint. Slightly verbose, but appropriately structured for the tool's 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?

Given 8 parameters, a nested completion object, no output schema, and no annotations, the description covers all major operation modes and constraints well. It explains when completion is required, how to reopen tasks, and how to attach skills. Missing return/error details would be nice, but they are not necessary 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 baseline is 3, but the description adds meaningful semantics beyond the schema: it wires done=true to the completion object, shows notes as progress-only, demonstrates valid parameter combinations with examples, and highlights skill_id attach behavior. It does not add much for block_id/item_id, but the schema already sources them.

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 ('Update a ctlsurf_task item') and enumerates the concrete operation modes: add progress notes, mark complete, reopen with feedback, and attach a skill. This clearly distinguishes it from sibling tools like update_block or update_checklist_item.

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 explicitly says 'Use to add progress notes, mark complete, or reopen with feedback' and gives callable examples for each mode. It does not explicitly list exclusions or direct alternatives, but for this dedicated task-item tool the provided use cases are clear enough to guide selection.

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?

With no annotations provided, the description carries full responsibility for disclosing behavior. It states that the tool updates fields but does not mention side effects, permanence, required permissions, or whether the folder must exist. It also does not clarify how the group field's null value is handled (removal), which is only in the schema. The description is silent on behavioral nuances that an agent needs for safe invocation.

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

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

The description is a single, concise sentence that front-loads the verb and resource, then enumerates the mutable attributes. There is no redundancy or filler; every word earns its place.

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

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

Given the tool's mutation nature, lack of annotations, and absence of an output schema, the description is incomplete. It does not specify what the tool returns (if anything), whether folder_id must be valid, or any error conditions. An agent cannot fully predict the outcome or requirements beyond the schema. More context is needed for a mutation 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 schema already documents all parameters. The description lists the updatable fields, which mirrors the schema but adds no additional meaning. It does not explain nuances like the group null semantics or interactions between fields. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description clearly states the action (update) and the resource (folder), and lists the specific attributes that can be modified: name, root_path, git_remote, hostname, or group. This distinguishes it from sibling tools like delete_folder, archive_folder, or get_folder. The verb-resource pair 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 provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or conditions that would lead an agent to choose update_folder over other folder-related tools (e.g., get_folder for retrieval, archive_folder for archiving). The context is implied only by the verb, leaving the agent to infer usage.

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

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

With no annotations provided, the description carries the full burden. It only states the action and gives examples, but does not disclose potential side effects such as whether existing property values are overwritten (e.g., do tags get replaced or appended?), permissions required, or idempotency. This is a significant gap for a 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 concise, with a clear opening statement followed by a bulleted list of examples covering each parameter. It is well-structured and front-loaded with the main purpose, making it easy to scan.

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

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

The description covers all parameters with examples, but for a mutation tool with no annotations and no output schema, it lacks important context such as the behavior of unspecified parameters (are they left unchanged?), whether tags are replaced or appended, and any error conditions. This leaves gaps for an agent to call it correctly in all cases.

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

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

The schema already provides 100% coverage with descriptions for all 7 parameters, so the baseline is 3. The description adds value by giving usage examples that show how parameters combine and the purpose of repo_url vs root_path (cross-machine support vs local path), which goes slightly beyond the schema 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?

The description clearly states 'Update a page's properties' and provides specific examples of the properties it can update (repo_url, root_path, title, parent_id, folder_id, tags). This distinguishes it from sibling tools like update_block and update_page_summary, making the purpose unambiguous.

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

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

The description explicitly states a specific use case ('Use this to link pages to codebases') and provides examples of different update scenarios. However, it does not explicitly state when not to use this tool or mention alternatives like update_block or update_page_summary, so the guidance is clear but lacks explicit exclusions.

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

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

With no annotations provided, the description must disclose behavioral traits, but it only says 'Create or update' implying a mutation. It does not mention idempotency, permissions, side effects, or what happens on partial input. For a write operation with zero annotation coverage, this is a significant gap.

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

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

The description is a single sentence that is front-loaded with the action and resource, then lists the metadata fields. It is concise, free of fluff, and every word earns its place.

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

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

For a mutation tool with no output schema and no annotations, the description is incomplete. It does not state what the tool returns, whether it is idempotent, or if it requires an existing page. Given the complexity of six parameters, an agent would need more context to use it confidently.

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 six parameters. The description adds value by grouping them as 'metadata' and naming the key ones, which reinforces the tool's purpose but does not introduce additional semantics beyond what the schema provides. 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 uses a specific verb 'Create or update' with a clear resource 'a page's summary block' and lists concrete metadata fields (summary, purpose, status, tags, key topics). This clearly distinguishes it from broader tools like update_page or read-only get_page_summary, though it does not explicitly name alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives such as update_page or create_page. The description only states what it does, not the context or conditions that would make it the preferred choice, and no exclusions or prerequisites are mentioned.

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