Server Quality Checklist

Tool Scores

• query-databaseD
  1.7/5.0
  Behavior1/5

  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. 'Query a database' offers no insight into whether this is a read-only operation, its performance characteristics, error handling, or any constraints (e.g., rate limits, authentication needs). It fails to describe what the tool actually does beyond the basic verb.

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

  Conciseness2/5

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

  While concise with just three words, this is under-specification rather than effective brevity. The description is too sparse to be helpful, failing to front-load critical information. It doesn't earn its place by adding value beyond the tool name.

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

  Completeness1/5

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

  Given the tool's complexity (5 parameters including nested objects, no output schema, and no annotations), the description is completely inadequate. It doesn't explain return values, error conditions, or behavioral nuances, leaving significant gaps for the agent to infer usage in a potentially critical operation like database querying.

  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%, meaning all parameters are documented in the schema itself. The description adds no additional meaning beyond what the schema provides (e.g., it doesn't explain how filters or sorts work in practice). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

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

  Purpose2/5

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

  The description 'Query a database' is essentially a tautology that restates the tool name 'query-database' without adding meaningful specificity. It doesn't distinguish this tool from potential alternatives like 'search' or 'list-databases' among the siblings, nor does it specify what kind of querying it performs (e.g., structured queries, filtered searches).

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

  Usage Guidelines1/5

  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 like 'search' or 'list-databases' among the siblings. There's no mention of prerequisites, context, or exclusions, leaving the agent with no usage direction beyond the vague purpose.

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

• update-pageC
  2.7/5.0
  Behavior2/5

  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 states 'Update an existing page', implying a mutation operation, but doesn't disclose permissions needed, whether changes are reversible, rate limits, or what happens to unmentioned properties. This is inadequate for a mutation tool with zero 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.

  Conciseness5/5

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

  The description is a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's purpose, making it easy to parse quickly.

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

  Completeness2/5

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

  Given the tool's complexity (mutation with 3 parameters, nested objects), no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral nuances, leaving significant gaps for an AI agent to understand how to use it effectively.

  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 schema already documents all three parameters (page_id, properties, archived). The description adds no additional meaning beyond what the schema provides, such as examples of properties or archiving implications. Baseline 3 is appropriate when the schema does the heavy lifting.

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

  Purpose3/5

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

  The description 'Update an existing page' clearly states the verb (update) and resource (page), but it's vague about what aspects can be updated and doesn't differentiate from sibling tools like 'update-block' or 'update-database'. It meets the basic requirement but lacks specificity.

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

  Usage Guidelines2/5

  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 like 'update-block' or 'update-database', nor does it mention prerequisites such as needing an existing page ID. It's a generic statement with no contextual usage information.

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

• append-block-childrenC
  2.9/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits such as permissions needed, whether appending is destructive to existing content, rate limits, or error handling for invalid block IDs, which are critical 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.

  Conciseness5/5

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

  The description is a single, efficient sentence with zero waste, front-loading the core action. It's appropriately sized for the tool's complexity, making it easy to parse quickly.

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

  Completeness2/5

  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 incomplete. It lacks context on what 'blocks' entail, how children are structured, potential side effects, or return values, leaving significant gaps for an agent to operate effectively.

  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 documented in the schema. The description adds no additional meaning beyond implying appending to a parent, which is already covered. Baseline 3 is appropriate as the schema handles parameter details adequately.

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

  Purpose4/5

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

  The description clearly states the action ('Append') and resource ('blocks to a parent block'), making the purpose understandable. It doesn't distinguish from siblings like 'update-block' or 'get-block-children', which could have overlapping contexts, so it's not fully differentiated.

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

  Usage Guidelines2/5

  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 like 'update-block' for modifying existing blocks or 'create-page' for adding new pages. The description lacks context about prerequisites or exclusions, leaving usage unclear.

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

• create-databaseC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. 'Create a new database' implies a write operation but doesn't specify permissions needed, whether this is idempotent, what happens on failure, or any rate limits. For a creation tool with zero annotation coverage, this leaves significant behavioral gaps.

  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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for the tool's complexity.

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

  Completeness2/5

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

  Given the tool creates a database (a complex operation with 5 parameters including nested objects), no annotations, and no output schema, the description is insufficient. It doesn't address what the tool returns, error conditions, or how it interacts with sibling tools like 'list-databases' or 'update-database'. More context is needed for effective use.

  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 well-documented in the schema itself. The description adds no additional parameter context beyond the basic action, which meets the baseline for high schema coverage. However, it doesn't explain relationships between parameters (e.g., how 'parent_id' relates to 'title') or provide usage examples.

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

  Purpose4/5

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

  The description 'Create a new database' clearly states the verb ('Create') and resource ('database'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create-page' or 'update-database', which would require more specificity about what distinguishes database creation from page creation or database updates.

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

  Usage Guidelines2/5

  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. With siblings like 'create-page', 'list-databases', and 'update-database', there's no indication of prerequisites, appropriate contexts, or when other tools might be more suitable. The user must infer usage from the tool name alone.

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

• create-pageC
  2.9/5.0
  Behavior2/5

  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 states this is a creation operation, implying mutation, but doesn't cover critical aspects like required permissions, whether the operation is idempotent, error handling, or what happens on success (e.g., returns a page ID). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

  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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place, achieving optimal conciseness for such a basic description.

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

  Completeness2/5

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

  Given the tool's complexity (3 parameters with nested objects, no output schema, and no annotations), the description is inadequate. It doesn't explain what 'properties' or 'children' entail in practice, what the tool returns, or any behavioral constraints. For a creation tool with multiple parameters and no structured support, more context is needed to be 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 description adds no parameter-specific information beyond what the schema provides. Since schema description coverage is 100%, the baseline score is 3. The schema already documents 'parent_id' as the database ID, 'properties' as page properties, and 'children' as optional content blocks, so the description doesn't enhance parameter understanding.

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

  Purpose4/5

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

  The description clearly states the action ('Create') and resource ('new page in a database'), making the tool's purpose immediately understandable. It distinguishes itself from siblings like 'create-database' (which creates databases rather than pages) and 'append-block-children' (which adds to existing pages). However, it doesn't specify what kind of database or platform this refers to, which keeps it from being fully specific.

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

  Usage Guidelines2/5

  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 doesn't mention prerequisites (e.g., needing an existing database), exclusions (e.g., not for updating pages), or comparisons to siblings like 'update-page' for modifications or 'create-database' for creating databases instead of pages. This leaves the agent with minimal context for tool selection.

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

• get-blockC
  2.9/5.0
  Behavior2/5

  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 states the action ('Retrieve') but doesn't describe what happens on failure (e.g., if the block ID is invalid), whether it requires authentication, rate limits, or the format of the returned data. For a read operation with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.

  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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place without redundancy or unnecessary elaboration.

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

  Completeness2/5

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

  Given the lack of annotations and output schema, the description is incomplete for a retrieval tool. It doesn't explain what a 'block' is in this context, what data is returned, or error handling. With no structured fields to rely on, the description should provide more context about the tool's operation and results, but it falls short.

  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 the single parameter 'block_id' clearly documented in the schema. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain block ID format or examples). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

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

  Purpose4/5

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

  The description clearly states the verb ('Retrieve') and resource ('a block'), making the purpose unambiguous. However, it doesn't differentiate this tool from similar siblings like 'get-block-children' or 'get-page', which also retrieve content by ID. The description is specific but lacks sibling distinction.

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

  Usage Guidelines2/5

  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. With siblings like 'get-block-children' (for child blocks), 'get-page' (for pages), and 'search' (for broader queries), there's no indication of when this specific retrieval by block ID is appropriate. 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.

• get-block-childrenC
  2.9/5.0
  Behavior2/5

  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 'retrieve' but doesn't specify if this is a read-only operation, what permissions are needed, how pagination works with 'start_cursor' and 'page_size', or what the return format is. This leaves significant gaps for an agent to understand the tool's behavior.

  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, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes directly to understanding the tool's purpose.

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

  Completeness2/5

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

  Given the complexity of a retrieval tool with pagination parameters and no output schema, the description is incomplete. It lacks details on behavioral aspects like permissions, pagination mechanics, and return values, which are crucial for an agent to use the tool effectively without annotations or output schema to fill these 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?

  The input schema has 100% description coverage, so parameters like 'block_id', 'start_cursor', and 'page_size' are well-documented in the schema. The description doesn't add any extra meaning beyond this, such as explaining what constitutes a 'block' or how pagination is handled, but the schema provides adequate baseline information.

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

  Purpose4/5

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

  The description clearly states the verb 'retrieve' and the resource 'children blocks of a block', making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get-block' or 'get-page', which might retrieve similar data but for different resources, leaving room for improvement in specificity.

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

  Usage Guidelines2/5

  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. With siblings like 'get-block' (which might retrieve block details) and 'get-page' (which might retrieve page details), there's no indication of when this tool is preferred, such as for hierarchical navigation or listing nested content.

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

• get-pageC
  2.9/5.0
  Behavior2/5

  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 states the tool retrieves a page but doesn't mention whether this is a read-only operation, what permissions are required, how errors are handled, or the format of the returned data. This leaves significant gaps in understanding the tool's behavior.

  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, efficient sentence that front-loads the core purpose ('Retrieve a page') without any wasted words. It is appropriately sized for a simple retrieval tool, making it easy for an agent to parse quickly.

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

  Completeness2/5

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

  Given the lack of annotations and output schema, the description is incomplete for a retrieval tool. It doesn't explain what data is returned (e.g., page content, metadata), error conditions, or behavioral traits like rate limits, leaving the agent with insufficient context to use the tool effectively.

  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 description coverage is 100%, with the single parameter 'page_id' fully documented in the schema. The description adds no additional meaning beyond what the schema provides (e.g., no details on ID format or sources), so it meets the baseline score of 3 for high schema coverage without extra value.

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

  Purpose4/5

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

  The description clearly states the action ('Retrieve') and resource ('a page by its ID'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get-block' or 'get-block-children', but the specificity of retrieving a page (not a block or database) is implied through the resource name.

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

  Usage Guidelines2/5

  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 like 'get-block' or 'search'. It lacks context about prerequisites (e.g., needing a valid page ID) or exclusions (e.g., not for retrieving blocks or databases), leaving the agent with minimal usage direction.

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

• searchC
  2.9/5.0
  Behavior2/5

  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 searching but doesn't describe what happens (e.g., returns results, pagination behavior, error conditions, or rate limits). The description is too vague to inform the agent about operational traits beyond the basic action.

  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, efficient sentence with zero waste—'Search Notion for pages or databases'—front-loading the core purpose without unnecessary elaboration. It's appropriately sized for a basic search tool.

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

  Completeness2/5

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

  Given the tool's complexity (5 parameters, nested objects) and lack of annotations or output schema, the description is incomplete. It doesn't explain return values, error handling, or behavioral nuances, leaving significant gaps for the agent to operate effectively in a Notion context.

  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 schema already documents all 5 parameters with descriptions. The description adds no additional meaning about parameters beyond what's in the schema (e.g., how 'filter' or 'sort' work in Notion context). Baseline 3 is appropriate as the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the action ('Search') and target ('Notion for pages or databases'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like 'query-database' or 'list-databases' that might also retrieve content, leaving room for ambiguity about when to use this versus those alternatives.

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

  Usage Guidelines2/5

  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 like 'query-database' or 'list-databases'. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer usage based on the tool name alone without clear differentiation from sibling tools.

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

• update-blockC
  2.9/5.0
  Behavior2/5

  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 mentions updating content and archive status, implying a mutation operation, but doesn't specify whether this requires specific permissions, if changes are reversible, what happens to existing content not mentioned, or any rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.

  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, efficient sentence that front-loads the core action ('Update a block's content or archive status') with zero wasted words. Every part of the sentence directly contributes to understanding the tool's purpose, making it highly concise and well-structured.

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

  Completeness2/5

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

  Given the tool's complexity (mutation operation with 4 parameters, no output schema, and no annotations), the description is insufficient. It doesn't explain what the tool returns, error conditions, or behavioral nuances like how 'archived' interacts with 'content' updates. For a tool that modifies resources, more context is needed to ensure safe and correct usage.

  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 description coverage is 100%, so the schema already documents all four parameters (block_id, block_type, content, archived) with clear descriptions. The description adds minimal value by hinting at the purpose of 'content' and 'archived', but doesn't provide additional syntax, format details, or examples beyond what the schema specifies. This meets the baseline for high schema coverage.

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

  Purpose4/5

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

  The description clearly states the verb ('Update') and resource ('a block's content or archive status'), making the purpose immediately understandable. It distinguishes this from creation tools like 'create-page' or 'create-database' by focusing on modification. However, it doesn't explicitly differentiate from other update tools like 'update-page' or 'update-database' beyond the resource type.

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

  Usage Guidelines2/5

  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 like 'update-page' (which might handle page-level blocks) or 'append-block-children' (which adds content rather than modifying existing blocks). There's no mention of prerequisites, such as needing the block_id from 'get-block', or exclusions for when this tool isn't appropriate.

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

• update-databaseC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden but offers minimal behavioral insight. 'Update' implies a mutation, but it doesn't disclose permission requirements, whether changes are reversible, side effects on related data, or error conditions. For a write operation with zero annotation coverage, this leaves critical behavioral traits unspecified.

  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, efficient sentence with zero wasted words. It's front-loaded with the core purpose, making it easy to parse quickly. Every word earns its place by conveying essential information without redundancy.

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

  Completeness2/5

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

  Given the complexity of updating a database (a mutation with nested objects and no output schema), the description is insufficient. It lacks details on what 'update' entails—such as partial vs. full updates, validation rules, or response format—leaving the agent with incomplete context for safe and effective use.

  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 fully documented in the schema. The description adds no additional meaning beyond implying that updates apply to 'an existing database', which is already clear from the schema's 'database_id' parameter. This meets the baseline for high schema coverage.

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

  Purpose4/5

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

  The description clearly states the action ('Update') and target resource ('an existing database'), making the purpose immediately understandable. It distinguishes from siblings like 'create-database' (creation vs. update) and 'list-databases' (read vs. write), though it doesn't explicitly differentiate from other update tools like 'update-block' or 'update-page'.

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

  Usage Guidelines2/5

  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 doesn't mention prerequisites (e.g., needing a database_id), exclusions, or comparisons to siblings like 'update-page' or 'create-database'. The 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.

• list-databasesB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool lists databases but doesn't describe return format (e.g., structure, pagination), permissions required, rate limits, or error conditions. For a read operation with zero annotation coverage, this is a significant gap in transparency.

  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, efficient sentence that front-loads the core purpose with zero wasted words. It directly states what the tool does without unnecessary elaboration, making it easy for an agent to parse and understand quickly.

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

  Completeness2/5

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

  Given no annotations and no output schema, the description is incomplete for a tool that returns data. It doesn't explain what the output looks like (e.g., list format, fields included) or behavioral aspects like pagination. For a read operation with rich sibling tools, more context is needed to guide effective use.

  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?

  The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds no parameter details, focusing on the tool's purpose. Baseline is 4 for zero parameters, as the description doesn't need to compensate for any schema gaps.

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

  Purpose4/5

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

  The description clearly states the action ('List') and resource ('databases'), specifying scope as 'all databases the integration has access to'. It distinguishes from siblings like 'query-database' (filtered query) and 'create-database' (write operation), though it doesn't explicitly name these alternatives. The purpose is unambiguous but lacks explicit sibling differentiation.

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

  Usage Guidelines2/5

  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 like 'query-database' for filtered queries or 'search' for broader content searches. The description implies usage for listing accessible databases but offers no context about prerequisites, timing, or exclusions. This leaves the agent without explicit usage instructions.

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