Server Quality Checklist

Tool Scores

• append_contentA
  3.8/5.0
  Behavior3/5

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

  Annotations already indicate non-read-only, non-idempotent, and non-destructive behavior. The description adds that it appends structural blocks and mentions placement options, but it does not disclose side effects, error conditions, or consequences of appending (e.g., whether blocks are inserted or duplicated). This is adequate but not extensive.

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

  Conciseness5/5

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

  The description is a single, focused sentence that front-loads the verb and resource. It clearly conveys the tool's purpose without unnecessary words or repetition of schema details.

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

  Completeness4/5

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

  Given the complex schema and output schema presence, the description is sufficiently complete. It captures the core action and key options, while the schema covers parameter details. No major contextual gaps are evident, though it could mention interaction with existing content or prerequisites.

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

  Parameters3/5

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

  Schema description coverage is 100%, so parameters are already well-documented. The description's mention of placement options (start, after a block, etc.) mirrors the schema's position enum and property descriptions without adding new semantic value beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the action ('Append'), the resource ('structural API 2.0 blocks to an existing object'), and the placement options (start, after a known block, inside a parent block, or in a specific block property). This differentiates it from siblings like append_content_markdown, which handles markdown content.

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

  Usage Guidelines3/5

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

  The description implies usage for structured blocks but does not explicitly state when to use this tool over alternatives like append_content_markdown or when not to use it. Sibling names hint at the distinction, but the description itself lacks explicit guidance or exclusions.

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

• create_objectA
  4.2/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context beyond these: the tool 'loads the live structure, rejects unsupported types and invalid properties, resolves label names, and accepts only strict documented API 2.0 blocks.' This explains the openWorldHint (loading live structure) and validation behavior. No contradictions with annotations. Could mention idempotency or side effects more explicitly, but current disclosure is strong.

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

  Conciseness5/5

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

  The description is two sentences with zero wasted words. The first sentence immediately states the core purpose and scope. The second sentence adds behavioral detail and points to the sibling tool. It is front-loaded, efficient, and every clause earns its place. Ideal conciseness for a tool with rich schema and annotations.

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

  Completeness4/5

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

  Given the tool has an output schema (return values not needing description), 6 parameters with complex nested blocks, and a sibling list, the description covers the essential behavioral contract: validation, live structure, label resolution, and alternative tools. It does not mention error handling specifics (e.g., what happens on invalid structure) or rate limits, but these are partially implied by 'rejects.' For a creation tool with this complexity, the description is nearly complete; a small gap is the lack of guidance on how the tool behaves with the openWorldHint (e.g., network dependencies).

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

  Parameters3/5

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

  Input schema has 100% description coverage, so each parameter already has meaningful documentation. The description adds general context about structure loading and strict block acceptance, which relates to the 'structure' and 'blocks' parameters. However, it does not introduce new parameter-specific details beyond what the schema provides. Baseline 3 is appropriate; the description reinforces but does not significantly extend parameter semantics.

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

  Purpose5/5

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

  The description clearly states the tool creates Capacities objects (Page, Tag, Task, custom structures) with a specific verb + resource. It distinguishes from sibling 'create_object_from_url' by explicitly noting that variant for weblinks, and from other creation tools by being the 'preferred structural creator.' The behavioral details (loads live structure, rejects unsupported types, resolves label names) add specificity to the purpose.

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

  Usage Guidelines4/5

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

  The description provides direct guidance on when to use this tool ('for Page, Tag, Task, or custom structures') and when not to ('Use create_object_from_url for weblinks'). It implies it should be used for structured object creation with validation. However, it does not address when to prefer 'create_object_markdown' or other siblings, missing a small opportunity for more exhaustive guidance. Still, the context is clear and actionable.

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

• create_object_from_urlA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint false, destructiveHint false, and idempotentHint false. The description adds a useful behavioral detail about 'optionally adding structural API 2.0 blocks' and clarifies the object type as 'web-resource'. However, it does not go beyond this, and no contradictions exist. This is adequate context 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.

  Conciseness5/5

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

  The description is only two sentences, front-loads the purpose, and includes a direct pointer to the alternative tool. Every sentence earns its place without redundant fluff.

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

  Completeness4/5

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

  Despite the tool's complexity (5 parameters, deep blocks schema, output schema), the structured fields are extraordinarily rich and self-explanatory. The description clearly communicates the core action, the object type, and selection guidance, which is sufficient for an agent to decide when to invoke it. It does not explain everything, but the structured data fills the gaps.

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

  Parameters3/5

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

  Schema description coverage is 100%, and each parameter (url, title, blocks, apiToken, description) already has detailed descriptions in the schema. The tool description itself adds no parameter-specific meaning beyond mentioning 'structural blocks', which is already covered by the blocks parameter description. Baseline 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool creates a Capacities web-resource object from a URL, using a specific verb and resource type. It also distinguishes itself from the sibling create_object_from_url_markdown by declaring itself the 'preferred URL-import tool' and qualifying when the Markdown variant should be used.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: 'This is the preferred URL-import tool; use create_object_from_url_markdown only when Markdown authoring is specifically requested.' This directly states when to use this tool versus the primary alternative, giving clear when/when-not context.

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

• create_object_from_url_markdownA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate this is not read-only, but the description adds useful behavioral context: conversion is lossy for exact underline styling, toggle details, Grid layout, and HTML background colors, and lossReport should be inspected. This goes beyond the structured annotation data.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, immediately followed by the alternative and a critical caveat. No wasted words or redundancy.

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

  Completeness4/5

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

  An output schema exists, so return values are covered structurally. The description covers purpose, distinguishes from the preferred alternative, and warns about lossy conversion. It could have explicitly stated when this tool is the best choice, but it is sufficiently complete for an agent.

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

  Parameters3/5

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

  The input schema has 100% description coverage with detailed parameter docs. The tool description only reiterates 'URL and Markdown' without adding new semantics 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.

  Purpose5/5

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

  The description clearly states the tool creates a Capacities web-resource object from a URL and Markdown notes, using the specific verb 'create' and naming the resource. It also distinguishes itself from the sibling create_object_from_url by calling that the 'preferred structural-block workflow', making its own purpose clear.

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

  Usage Guidelines4/5

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

  The description explicitly mentions an alternative (create_object_from_url) and characterizes this tool differently ('explicit Markdown' vs structural-block). It also warns that conversion is lossy and advises inspecting lossReport, which helps the agent decide whether to use this approach.

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

• delete_blockA
  4.2/5.0
  Behavior4/5

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

  Annotations already include destructiveHint=true, but the description adds valuable context beyond that: nested child blocks are deleted with the parent, implying cascade deletion. It also adds a precautionary note to read structured content first. This enriches the behavioral model without contradicting annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, then a crucial caution about nested deletions. Every word earns its place, and there is no redundancy or filler. It is highly scannable and effective.

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

  Completeness4/5

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

  Given that an output schema exists and the annotations cover the destructive nature, the description provides sufficient context for a delete tool. It explains the core action, the cascade deletion behavior, and offers a safety guideline. It could optionally mention response behavior, but the output schema likely covers that, so no significant gap exists.

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

  Parameters3/5

  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 references 'object ID and block ID' which maps to the 'id' and 'blockId' parameters, but adds no additional meaning beyond the schema's descriptions. The apiToken parameter is not mentioned, but the schema already covers it thoroughly.

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

  Purpose5/5

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

  The description clearly states 'Delete one existing Capacities block by object ID and block ID', using a specific verb and resource. It distinguishes from sibling tool 'delete_object' by targeting blocks, and the title reinforces this. This is a clear, non-tautological purpose statement.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance: 'read structured content first and use only when the deletion is intentional.' It also highlights a key consequence ('Nested child blocks are deleted with their parent'), which helps the agent decide when to use the tool. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls short of a 5.

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

• delete_objectA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, but the description adds meaningful context by differentiating trash (recoverable) from permanent (irreversible). This goes beyond the boolean hint, though it does not mention side effects on related objects or permission requirements.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, and no redundant phrasing. Every clause adds value: the first sentence states the action, the second explains the safety default and permanent override.

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

  Completeness4/5

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

  For a single-object delete operation, the description covers the essential behavior and parameter toggle. It leaves out potential side effects (e.g., cascading deletes, reference integrity) and permission notes, but given the presence of an output schema and rich annotations, it is near-complete.

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

  Parameters3/5

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

  Schema coverage is 100%, and the description adds no additional meaning for the 'id' or 'apiToken' parameters beyond what the schema already provides. The mention of 'permanent=true' echoes the schema's own description, so the description does not enhance parameter understanding.

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

  Purpose5/5

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

  The description opens with 'Delete a Capacities object', a specific verb+resource pairing that immediately clarifies what the tool does. The resource 'Capacities object' distinguishes it from sibling tools like delete_block, which targets a different entity.

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

  Usage Guidelines4/5

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

  The description gives clear operational guidance: the safe default moves to trash, while permanent deletion requires permanent=true. It does not explicitly name alternatives or exclusion scenarios, but the trash-vs-permanent distinction implies a recommended usage path, which is adequate for this simple delete tool.

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

• get_objectA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context about format semantics – structured JSON is safe for edit pipelines, while markdown is a compact read-only view. This goes beyond the annotation hints by clarifying how the output should be consumed in an editing workflow.

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

  Conciseness5/5

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

  Two sentences, with the core action front-loaded in the first sentence and the format guidance in the second. No filler or redundant elaboration – every clause earns its place.

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

  Completeness4/5

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

  For a read-by-UUID tool with an output schema and comprehensive annotations, the description covers the essential purpose, the format decision, and edit-safety implications. It doesn't discuss error handling or pagination, but those are less critical given the output schema and the simple single-object retrieval scope. The sibling context suggests search_objects is the alternative for querying, which is implicitly clear.

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

  Parameters3/5

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

  Schema coverage is 100% – all three parameters (id, format, apiToken) have detailed descriptions covering UUID format, enum values, defaults, and security constraints. The description's mention of structured vs markdown partially echoes the schema's format description but adds no new parameter-level information, so it stays at the baseline for high schema coverage.

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

  Purpose5/5

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

  The description starts with 'Read one Capacities object by UUID' – a specific verb, resource, and lookup method. It clearly differentiates from sibling tools like search_objects (search), update_object (mutate), and delete_object (delete), establishing this as the canonical read-by-ID operation.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use each format: structured for follow-up edits, markdown for read-only proposal/context views. It doesn't explicitly name alternatives like search_objects for finding objects by criteria, but the UUID-based read scope is evident, so the tool's place is clear enough.

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

• inspect_spaceA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining the distinction between the two output modes (compact catalog vs. detailed schema) and by noting the tool is token-bound. It does not contradict annotations. It could add more about caching/refresh behavior, but the schema covers that.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose, and efficiently conveys both modes and a usage recommendation. Every sentence earns its place without repeating schema information or annotations. This is concise and well-structured.

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

  Completeness4/5

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

  Given the rich annotations, full schema coverage, and an output schema, the description covers the essential behavior and usage context. It does not describe return values in detail, but the output schema handles that. It could mention the refresh parameter's purpose, but the schema already covers it. Overall, it is nearly complete for an inspection tool with this level of structured metadata.

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

  Parameters3/5

  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 minimal parameter meaning beyond the schema—it mentions 'structure ID/name' which aligns with the structure parameter, but refresh and apiToken are not described in the tool description. Since the schema already fully documents parameters, a score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('Inspect') and resource ('Capacities space'). It distinguishes between two modes—without a structure returns an object-type catalog, and with a structure ID/name returns schema details—which differentiates it from sibling tools like get_object or search_objects. This is a precise and unambiguous purpose statement.

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

  Usage Guidelines4/5

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

  The description explicitly advises calling this tool before unfamiliar create/update operations, providing clear when-to-use guidance. It does not explicitly mention when not to use it or name alternative tools, but the context of sibling mutation tools makes the usage obvious. This earns a 4 rather than a 5 due to the lack of explicit exclusions or alternatives.

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

• manage_upload_jobA
  4.2/5.0
  Behavior4/5

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

  Annotations mark the tool as destructive. The description adds valuable context: 'cancel aborts pending sessions while preserving already completed media objects.' It also clarifies that status is immediate and wait blocks up to timeoutSeconds, providing behavioral details beyond the annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with purpose, and every word earns its place. It efficiently explains the three actions without redundancy.

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

  Completeness4/5

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

  Given the tool's moderate complexity, the description covers key behaviors and cancellation side effects. An output schema exists for return values, so not explaining them is acceptable. A minor gap is lack of guidance for invalid job IDs or already-terminal jobs, but overall it is complete.

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

  Parameters3/5

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

  Schema descriptions cover 100% of parameters. The description reinforces the action semantics ('status is immediate, wait blocks...') but does not add syntax or format details beyond what the schema already provides, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses the specific verb 'Manage' and identifies the resource as an 'in-process Capacities upload job returned by upload_files in background mode.' It enumerates the three actions (status, wait, cancel), which clearly distinguishes it from sibling content/upload tools.

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

  Usage Guidelines4/5

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

  The description clearly states the tool is for managing jobs from upload_files in background mode, giving the context of when to use it. It does not explicitly name alternatives or exclusion criteria, but the scope is well-defined and distinct from siblings.

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

• append_daily_noteA
  4.4/5.0
  Behavior5/5

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

  Critically discloses that the API queues the write asynchronously, so success means accepted/queued rather than immediately readable. This is valuable behavioral context beyond the annotations, which do not mention async semantics. No contradiction with annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core action, and zero wasted words. The async caveat is essential and placed immediately after the purpose.

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

  Completeness4/5

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

  Given the intricate block schema and the presence of an output schema, the description plus schema cover the essentials well. A slight gap is not explicitly pointing to the markdown sibling alternative, but the tool name and description make the structural purpose clear enough.

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

  Parameters3/5

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

  Schema description coverage is 100%, so parameters are already fully described in the input schema. The tool description adds only that blocks should be structural API 2.0 blocks and date defaults to today, but does not elaborate on parameter formatting beyond the schema.

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

  Purpose5/5

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

  The description uses a specific verb ('Append') and resource ('daily note') with the qualifier 'structural API 2.0 blocks', clearly distinguishing it from the sibling append_daily_note_markdown. It also specifies the date targeting (today's or a specified note).

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

  Usage Guidelines4/5

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

  The description provides clear context that this is for structural block appends and mentions the async behavior, which guides usage expectations. It does not explicitly name alternates like append_daily_note_markdown or state when not to use this tool, but the name and context make the intended use clear.

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

• upload_filesA
  4.5/5.0
  Behavior5/5

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

  Though annotations already indicate a mutating, open-world, non-idempotent operation, the description adds significant behavioral detail: 'Streams multipart files without loading them into the model or memory, verifies each completed object with GET, and returns partial results when independent files fail.' This transparency goes well beyond the structured annotations.

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

  Conciseness5/5

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

  The description is three sentences: purpose, key behavioral traits, and usage guidance. It is front-loaded and concise, with every sentence contributing meaningful information and no redundancy.

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

  Completeness5/5

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

  Given the tool's complexity, the description covers streaming, verification, partial failures, and background processing, and it points to manage_upload_job for lifecycle control. With an output schema present, there is no need to explain return values, making this contextually complete.

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

  Parameters3/5

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

  The schema already provides 100% parameter descriptions, including mode options, file path rules, and API token behavior. The description only references mode=background without adding new parameter-level semantics, so the default baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states the verb and resource: 'Upload one or more local files to Capacities as media objects.' It distinguishes from siblings by explicitly focusing on local file uploads and media objects, and it references manage_upload_job for background job handling, making the tool's role clear.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance for when to use background mode: 'Use mode=background for long or large batches, then manage_upload_job for status, wait, or cancel.' It names a complementary tool but does not explicitly state when not to use upload_files versus other content creation tools, so it falls slightly short of full exclusion guidance.

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

• list_objectsA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the description's main behavioral value is its mention of pagination and returning summaries. No contradiction observed. The description adds the 'one cursor-paginated page' nuance which is not in annotations, earning credit above baseline.

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

  Conciseness5/5

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

  The description is one efficient sentence with front-loaded action and differentiation. Every word adds value, no redundancy or filler. Perfectly sized for quick scanning.

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

  Completeness4/5

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

  For a tool with good annotations and a rich schema, the description is fairly complete. It covers purpose, alternatives, and pagination. The output schema exists, so return values need no explanation. Minor gaps: doesn't mention that results are summaries or what fields the summary includes, but given openWorldHint, this is acceptable.

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

  Parameters4/5

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

  Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying that filter must have exactly one membership target and listing the three types (structure, tag, collection), which is already in the schema but re-iterated helpfully. The cursor and pageSize semantics are well-documented in schema; description doesn't add much beyond but is adequate.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and the resource 'one cursor-paginated page of Capacities object summaries', specifying the filtering dimensions (structure, tag, or collection). It provides clear differentiation from sibling tools like search_objects and get_object.

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

  Usage Guidelines5/5

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

  The description explicitly tells when to use this tool versus alternatives: 'Use search_objects for title matching and get_object for full object content.' It also implies paging via cursor, providing clear context with no misleading guidance.

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

• update_objectA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the key partial-update semantic: 'Supplied fields replace that property; omitted fields stay unchanged.' This goes beyond annotations and clarifies idempotent behavior. It does not cover error cases, but the annotations + schema reduce that burden.

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

  Conciseness5/5

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

  Two sentences, each carrying essential information: the update targets plus the replacement behavior and the pointer to body-content tools. No filler or repetition of schema detail.

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

  Completeness4/5

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

  Given the complex nested schema and output schema, the description covers the key prerequisites, the partial-update behavior, and tool alternatives. It does not exhaustively discuss error behavior, but the schema and annotations supply parameter-level and safety details, so the description is adequately complete for agent decision-making.

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

  Parameters4/5

  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 supplements it by clarifying replacement semantics for fields and collections with 'Supplied fields replace that property; omitted fields stay unchanged,' which the schema alone does not state. This adds meaningful semantic value for the fields/collections parameters.

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

  Purpose5/5

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

  The description explicitly states the verb and resource: 'Update an object's title, writable typed properties, or collections.' This clearly distinguishes it from sibling tools like update_block and append_content by scoping exactly what it modifies and by directing body-content work to alternatives.

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

  Usage Guidelines5/5

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

  The description says 'after loading its live structure schema,' which establishes a prerequisite for safe use, and explicitly names alternatives: 'Use append_content or update_block for body content.' This is direct when-to-use guidance vs. siblings.

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

• append_content_markdownA
  4.7/5.0
  Behavior5/5

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

  The description goes beyond the annotations by disclosing that Markdown conversion is lossy for specific formatting elements and instructs to inspect lossReport. This is critical behavioral context that annotations do not provide.

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

  Conciseness5/5

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

  The description is only two sentences long, with the first sentence stating purpose and alternative, and the second stating the lossy caveat and needed action. There is no wasted wording or redundant information.

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

  Completeness5/5

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

  Given the detailed schema with 100% parameter coverage, an output schema, and annotations indicating a mutating operation, the description covers the essential contextual points: what the tool does, when to prefer an alternative, and what behavioral caveat to expect. It is complete enough for an agent to invoke the tool correctly.

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

  Parameters3/5

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

  The input schema has 100% description coverage for all parameters, each with clear descriptions. The tool description adds no additional parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'Explicitly append Markdown to an existing object' with a specific verb, resource, and content format. It also distinguishes itself from the sibling tool append_content by positioning it as the Markdown-specific alternative.

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

  Usage Guidelines5/5

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

  The description explicitly says 'Use append_content for the preferred structural JSON-block workflow,' providing a clear alternative. It also warns about lossy conversion for exact underline styling, toggle details, Grid layout, and HTML background colors, indicating when this tool may not be suitable.

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

• append_daily_note_markdownA
  4.7/5.0
  Behavior5/5

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

  The description adds critical behavioral details not present in annotations: the API queues writes asynchronously, lossReport is preflight-only, and Markdown conversion is lossy for underline styling, toggle details, Grid layout, and HTML background colors. This goes beyond the basic write indication from readOnlyHint=false.

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

  Conciseness5/5

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

  Two sentences convey the purpose, alternative, async behavior, and lossiness without redundancy. The primary action is stated first, followed by essential caveats, with no fluff.

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

  Completeness5/5

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

  With an output schema present and annotations covering basic safety, the description provides all necessary context: the tool's action, when to use the alternative, the async nature, and lossy conversion caveats. No critical gaps are apparent for a write tool of this complexity.

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

  Parameters3/5

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

  The schema provides descriptions for all 4 parameters, giving 100% coverage. The tool description does not add parameter-specific meaning beyond the schema, though it hints at Markdown formatting limitations that could affect the markdown parameter. This meets the baseline for full schema coverage.

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

  Purpose5/5

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

  The description opens with 'Explicitly append Markdown to a Capacities daily note', a specific verb+resource statement. It distinguishes this tool from the sibling append_daily_note by labeling that as the preferred structural JSON-block workflow, making the tool's unique role clear.

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

  Usage Guidelines5/5

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

  The description explicitly directs users to append_daily_note for the preferred structural workflow, naming an alternative. This implies this tool is for explicit Markdown writes, giving clear guidance on when to use it versus the sibling tool.

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

• create_object_markdownA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (which are readOnlyHint=false, destructiveHint=false, etc.), the description reveals that Markdown conversion is 'lossy' for specific styling elements and instructs the agent to inspect a 'lossReport' in the response. This adds critical behavioral context about what information may be lost and how to detect it, which annotations do not cover.

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

  Conciseness5/5

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

  The description consists of two concise sentences. The first immediately states the purpose, and the second delivers usage guidelines and behavioral warnings. Every sentence earns its place with no redundancy or filler, and the critical information is front-loaded.

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

  Completeness5/5

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

  Given the tool's complexity (6 parameters, nested objects, output schema exists), the description is complete. It covers the tool's purpose, when to use it vs. alternatives, behavioral caveats, and references the lossReport. The output schema is present, so return values need not be described. The description adequately fills gaps beyond the schema and annotations.

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

  Parameters3/5

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

  Schema description coverage is 100%, so each parameter already has a description in the input schema. The tool description does not add further parameter-level meaning beyond the schema. While it sets general context, it meets the baseline expectation of 3 for a fully covered schema.

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

  Purpose5/5

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

  The description clearly states 'Explicitly create a Capacities object from a Markdown body', using a specific verb (create) and resource (Capacities object from Markdown). It also directly distinguishes from the sibling tool create_object by mentioning the 'preferred structural JSON-block workflow', making the agent aware of which tool to choose.

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

  Usage Guidelines5/5

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

  The description explicitly advises when to use this tool (Markdown body) and when not to use it (when exact styling of underline, toggle details, Grid layout, or HTML background colors is needed). It names the alternative tool (create_object) and provides actionable guidance to 'inspect lossReport' after conversion, giving clear decision criteria.

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

• search_objectsA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying exact search scope (title-only, no body/properties), return format (IDs and titles), and filtering behavior (optional structures). No contradictions.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the tool's primary purpose, immediate constraints, and follow-up usage. No filler or redundancy.

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

  Completeness5/5

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

  Given the tool's moderate complexity, rich schema with 100% coverage, complete annotations, and presence of an output schema, the description fully covers what the tool does, its constraints, and how its output is used. No gaps remain.

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

  Parameters4/5

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

  Schema covers 100% of parameters with descriptions. The description adds no additional param semantics, but this is acceptable since schema coverage is high and the baseline is 3. Extra point for clarifying that apiToken must not be echoed or copied from content, which is security-critical guidance not in the schema.

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

  Purpose5/5

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

  States clearly that it searches Capacities objects by title only, with optional filtering by structures. Distinguishes itself from siblings like get_object (single object retrieval) and list_objects (unfiltered listing) by specifying the search scope and constraints.

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

  Usage Guidelines4/5

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

  Explicitly says when to use this (title-only search for objects) and what it does not search (body blocks or property values). Mentions that results include IDs and titles for use with get_object or relation fields. Could further clarify when to prefer siblings like list_objects or get_object.

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

• update_blockA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses crucial semantics: strict structural API 2.0 JSON, the requirement that the type must match, and that omitted blocks/columns preserve children while supplied children replace them. This gives the agent the exact behavioral rules needed to avoid data loss, exceeding the annotation-only signal.

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

  Conciseness5/5

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

  Three sentences, no filler: verb, resource, prerequisite, and key behavioral rule. Each sentence carries essential information, and the most important verb is front-loaded.

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

  Completeness5/5

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

  For a tool with an intricate recursive block schema, the description covers the prerequisite read, the type constraint, and the destructive/preserve behavior around children. With an output schema present, no return-value explanation is needed; the instructions are sufficient for correct invocation.

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

  Parameters4/5

  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 meaningful semantics for the central 'block' parameter by explaining the preserve-vs-replace behavior and the type-matching constraint. This enriches the schema definitions and warrants a 4.

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

  Purpose5/5

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

  The description opens with a specific verb ('Update') and resource ('existing Capacities block'), clearly distinguishing it from sibling tools like update_object (whole object) and create_object (creation). It also adds 'in place' and 'strict structural API 2.0 JSON', leaving no ambiguity about what the tool operates on.

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

  Usage Guidelines4/5

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

  It explicitly instructs to 'Read get_object in structured mode first,' establishing a required precondition and workflow. However, it does not directly contrast with update_object or state when to prefer this over alternative update/creation tools, so it stops short of a 5.

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