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

With no annotations, the description carries the full burden and does well: it discloses that existing content is never modified/removed, that content is appended to the end, and that empty/whitespace-only markdown is rejected before contacting Notion. This goes well beyond the bare schema, though it does not cover permissions, failure modes, or rate limits.

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

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

Every sentence earns its place. The main behavior and return shape are front-loaded, followed by compact parameter definitions and a validation note. No repetition or filler.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers the essential context: what the tool does, what it returns, what each parameter means, and a key edge-case behavior. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate. It does: ref is defined as an alias, notion.so URL, id, or exact page title, and markdown is defined as the same supported subset as create_page with explicit validation behavior. This is exactly the semantic detail the schema lacks.

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

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

The description names a specific action (append) and resource (page), states the return shape {appended, url}, and explicitly distinguishes its non-destructive nature from other page operations. This is unambiguous and differentiates it from siblings like create_page and update_row.

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

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

The behavior clearly implies this is for adding content to an existing page rather than creating or updating, and references create_page for markdown semantics. However, it does not explicitly state when to choose this tool over a sibling or mention exclusion conditions.

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

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

Without annotations, the description carries the behavioral burden, and it does disclose non-obvious behavior: unsupported markdown fails before Notion is touched, and properties are only accepted for database parents. It still omits return-shape and permission/rate-limit context, but the key side-effect and failure semantics are not hidden.

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

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

The description is compact and front-loaded, with each clause adding a distinct fact needed for correct invocation. There is no filler or repetition of schema boilerplate.

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

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

For a write tool with no annotations and no output schema, it covers all four parameters, the markdown failure mode, and the get_database_schema prerequisite. Missing return/response detail and permissions are minor gaps, but an agent can invoke it correctly from this text alone.

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

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

With 0% schema description coverage, this is the description's strongest contribution. It enumerates accepted parent_ref formats (alias, notion.so URL, id, or exact title), explains the title-with-database-parent rule, lists supported markdown constructs, and scopes properties to database parents with a prerequisite call. This fully compensates for the bare schema.

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

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

The description opens with a specific verb and resource—'Create a page'—and defines the two contexts: as a row in a database or as a subpage of another page. This makes it clearly distinct from sibling tools like append_to_page and update_row.

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

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

It gives concrete when-to-use guidance by telling the agent to call get_database_schema first for a database parent and restricting properties to that case. It also instructs the agent to set the title directly rather than through properties. It doesn't explicitly name exclusions against append_to_page, but the creation-vs-modification context is clear.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals the return structure and positions the tool as a read-only prerequisite for query/write operations, strongly implying no side effects. It does not explicitly state error behavior or auth needs, but for a simple getter this is a minor gap.

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

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

Three sentences with no redundant words. The purpose and return format are front-loaded, followed by clear usage guidance and parameter semantics. Every sentence earns its place.

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

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

The tool is simple (one required parameter, no output schema), and the description covers purpose, usage order, return shape, and parameter values. It also places the tool among siblings via the usage instruction, leaving no critical information missing for an agent to invoke it correctly.

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

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

The input schema only names the parameter 'ref' with no description, and schema coverage is 0%. The description fully compensates by defining all accepted forms: 'an alias, a notion.so URL, an id, or an exact database title'. This gives the agent complete semantic grounding for the parameter.

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

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

The description states the tool returns 'Property names and types for a database' with a specific output shape '{title, url, properties}'. It distinguishes itself from siblings by instructing to call it before query_database or update_row, making its role as a schema-fetching step clear.

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

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

It explicitly says 'Call this before filtering with query_database or writing with update_row', giving a direct when-to-use instruction that routes the agent away from alternatives. It also specifies the accepted ref formats, which implicitly clarifies when the tool is applicable.

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

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

With no annotations, the description caries the full disclosure burden. It meaningfully discloses the return envelope and a conversion behavior: unsupported block types appear as '<!-- unsupported: TYPE -->' comments. It doesn't cover not-found errors or permissions, but the getter nature is apparent and the output behavior is usefully detailed.

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

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

The description is compact, front-loaded with the response shape, and each clause earns its place: return fields, markdown/unsupported-block behavior, and ref formats. There is no filler or repetition of schema information.

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

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

For a one-parameter retrieval tool with no output schema, the description covers the return object, the markdown conversion caveat, and valid ref forms. It is slightly incomplete in not pointing to sibling tools for discovery workflows or describing not-found behavior, but those are secondary given the simple operation.

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

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

The input schema only says 'ref' is a required string with no description, and schema coverage is 0%, so the description is the only parameter documentation. It adds substantial meaning by enumerating accepted ref formats: alias, notion.so URL, id, or exact page title. It doesn't define 'alias' further, but it is a clear gain over the schema.

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

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

The description identifies the resource (a Notion page) and the shape of what the caller recieves ({title, url, properties, markdown}), so an agent can tell this returns page content rather than a schema or database list. It doesn't use an explicit verb such as 'retrieve' or 'fetch' and doesn't contrast with siblings like search or query_database, so it stops short of the top tier.

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

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

Usage is implied by the tool name and by the 'ref' field, which lists accepted inputs (alias, notio.so URL, id, or exact title). However, the description never says when to choose this over query_database, search, or list_databases, and provides no exclusions or alternatives.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses that only databases 'visible to this integration' are returned, and it explains the alias semantics: aliases can resolve to not-yet-visible databases and remain usable as a 'ref'. It also indicates the output shape and the null-title edge case, which is valuable beyond the raw operation name.

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

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

The description is concise and front-loaded: the first sentence states the action and output shape, the second defines 'alias', and the third covers the important edge case. Every sentence contributes information without verbosity.

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

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

For a zero-parameter listing tool with an existing output schema, the description is effectively complete. It covers access scope, output fields, alias semantics, and the edge case where an alias does not match a visible database. Nothing critical appears to be missing for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so there is little to explain. Schema description coverage is 100% and the schema is empty, meaning no parameter ambiguity exists. The description adds meaningful context about alias resolution that an agent needs when working with database references.

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

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

The description clearly states a specific action and resource: 'List Notion databases visible to this integration.' It also specifies the output shape '{title, url, alias}', making the tool's purpose unambiguous. This distinguishes it from siblings like query_database or get_page, which operate on a single database or page rather than listing all visible databases.

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

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

The description implies the tool is for enumerating available databases, but it does not explicitly discuss when to choose it over alternatives such as search or get_database_schema. There is no exclusion guidance or sibling comparison. The usage context is clear enough for a simple listing tool, but not fully specified.

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

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

The description discloses output shape and key query semantics: filters combine with AND, text properties match by substring while others match by equality, and sort expects a specific object shape. This adds meaningful behavioral detail beyond the sparse annotations, though pagination and error behavior are not covered.

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

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

The description is compact and well-structured, with the output shape stated first and each parameter described on its own line. There is no filler; every sentence adds operational value.

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

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

For a read-only query tool with an output schema, this description covers the core contract: target, parameters, and result shape. It only lacks explicit sibling routing and pagination/error details, which are secondary for a filtered query.

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

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

Schema coverage is 0%, but the description fully documents all four parameters with concrete formats: ref alias types, filter object semantics, sort direction enum, and limit meaning. This compensates for the generic additionalProperties schemas and gives an agent enough detail to construct valid arguments.

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

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

The description identifies querying rows of a Notion database and specifies the returned shape {title, url, properties}. It distinguishes itself from siblings like list_databases by focusing on row retrieval, though it does not explicitly contrast with related tools like search or get_page.

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

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

It gives practical guidance on ref formats and says property names must come from get_database_schema, which is a useful routing hint. However, it does not state when to prefer this tool over alternatives such as search or get_page, nor does it mention when not to use it.

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

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

With no annotations, the description carries the behavioral burden. It discloses the result limit ('at most 25 matches'), advises narrowing the query, and explains the behavior of the kind parameter. It does not cover all edge cases, but the essential behavior is transparent.

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

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

The description is compact and front-loaded. Every sentence adds useful information: purpose, result shape, use case, result limit, and kind semantics. There is no filler or repetition.

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

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

For a simple two-parameter search tool with an output schema, the description is nearly complete. It covers purpose, parameters, result limit, and return shape. The only minor gap is explicit guidance on when to choose this over sibling tools like list_databases.

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

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

Schema coverage is 0%, so the description must compensate. It explains the kind parameter well ('page', 'database', or omitted for both), but the query parameter is only implicitly described through 'Search titles.' More detail on matching behavior would be helpful, though the parameter is relatively self-explanatory.

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

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

The description states a specific verb and resource ('Search titles of pages and databases shared with this integration') and gives the output shape. It clearly distinguishes this tool from siblings like list_databases or query_database by framing it as a lookup to find a URL to pass as a ref.

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

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

The description gives a clear use case: 'Use it to find the URL to pass as a ref.' It implies the tool is for discovery rather than data retrieval or mutation, though it does not explicitly name alternative tools or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals a key behavior: only named properties change and the page body is untouched. But for a mutation tool, it does not disclose whether this is a partial update (PATCH-like) or replaces the entire row, what auth/permissions are needed, how invalid property names or values are handled, or whether changes are reversible. These gaps leave the agent with incomplete behavioral context.

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

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

The description is compact and dense, with every line contributing useful info. The core behavior is front-loaded, followed by concise parameter definitions. The bullet-like formatting for ref and properties is scannable and doesn't waste tokens. It earns a 4 because it is efficiently structured, though the two-line breaks are slightly unnecessary.

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

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

Given zero annotations and no output schema, the description provides a usable but incomplete picture. It explains what the tool does, what the two parameters mean, and the recommended prerequisite call. But it lacks details on return value (does it return the updated row?), error pehavior for non-existent refs or invalid properties, and rquirements like write permissions. For a mutation tool, this is enough to start but not fully self-sufficient.

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

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

The schema is minimal: ref is just a string and properties is an open object. The description compensates significantly by explaining the accepted ref formats (alias, notion.so URL, id, or exact row title) and that properties is a property-name-to-value mapping. However, it doesn't add guidance on how to structure complex values (e.g., select/status options, multi-select, date format), which is a common Notion API pain point.

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

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

The description starts with a specific verb and resource: 'Set properties on a database row.' It clearly distinguishes the operation from page-body edits by stating 'the page body is untouched.' It does not explicitly differentiate from create_row or append_to_page, but the combination of 'update' in the name and the explicit scope makes the purpose clear.

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

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

The description implies when to use this tool by stating it only affects named properties and not the page body, which contrasts with sibling operations like append_to_page. It also gives the prerequisite 'Call get_database_schema first' for valid names/options. However, it never explicitly states when to prefer this over create_row, query_database, or other siblings, so the usage guidance is mostly implied.

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