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

No annotations are present, so the description carries the full behavioral disclosure burden. It states that counting is a read operation and that a filter is optional, but it does not disclose return format, edge cases, performance implications, or any limitations.

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

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

The description is a single, efficient sentence that immediately states the core action and the optional filter. There is zero wasted text and it is front-loaded.

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

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

Given the simplicity of a count operation, the description covers the basic purpose but lacks essential context: with no output schema, it should specify the return type (e.g., an integer count) and any relevant behavior such as how counts handle empty results. It is minimally complete but leaves gaps.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's lack of explanatory text. It only loosely maps 'table' to table_id and 'filter' to where, without explaining the filter syntax or format. This is insufficient for correct invocation.

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

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

The description uses the specific verb 'Count' and identifies the resource as 'records in a table', clearly distinguishing it from siblings like list_records or get_record. The optional filter adds precision about scope.

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

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

No guidance is provided on when to use count_records versus alternatives such as list_records or get_record. The description does not mention exclusions, prerequisites, or alternative tools, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description carries the full burden. It mentions batch creation ('one or more') but does not disclose potential side effects, permissions required, error behavior, or whether created records receive IDs. A mutation tool with zero annotation coverage should provide more 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 a single, concise sentence with no filler. It effectively conveys the core purpose without waste.

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?

This is a mutation tool with no annotations, no output schema, and an undocumented required parameter (table_id). The description does not cover return values, failure modes, or any prerequisites such as needing to call get_table_schema first. It is incomplete for safe and correct invocation.

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

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

Schema coverage is 50%: only 'records' has a description, while 'table_id' is not described. The tool description adds no parameter-level explanation beyond the schema. With half the parameters undocumented and no description compensation, parameter semantics are weak.

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 'Create one or more records in a table' clearly states the action (create), the resource (records), and the scope (a table). It distinguishes from sibling tools like update_records and delete_records through the verb 'create' and supports both single and batch creation.

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 usage for inserting new records but does not explicitly state when to use this tool versus alternatives like update_records or when not to use it. No exclusions or alternative recommendations are provided, leaving the agent to infer from the verb 'create'.

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

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

No annotations are present, so the description must carry the burden of behavioral disclosure. It only says 'Delete' without mentioning irreversibility, permissions, consequences for linked records, or batch-delete behavior, which is minimal disclosure for a destructive operation.

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

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

The description is a single, front-loaded sentence with no filler words. It is concise, though the brevity sacrifices valuable contextual information, making it somewhat under-specified for a destructive tool.

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 relatively simple, but the description omits important details such as return values, batch-delete semantics, and irreversibility. With no output schema and no annotations, the description leaves the agent with only a basic understanding of the full operation.

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

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

The schema documents 'ids' as a single Id or list, but 'table_id' has no schema description, and schema description coverage is only 50%. The description adds no extra meaning beyond the word 'Id', failing to compensate for the undocumented 'table_id' 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 uses the specific verb 'Delete' with resource 'records' and the selection mechanism 'by Id', which clearly distinguishes it from sibling tools like create_records, update_records, and list_records. It precisely states what the tool does.

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

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

No guidance is provided about when to use this tool versus alternatives, prerequisites, or exclusion cases. The description only states the action, leaving the agent to infer when deletion is appropriate 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.

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

No annotations are provided, so the description must bear the full burden of behavioral disclosure. It only states that the tool performs a 'get' operation, which implies read-only behavior, but does not disclose error handling (e.g., whether a missing record throws an error or returns null), permission requirements, or rate limits. The description adds no context beyond the operation itself.

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

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

The description is one short sentence that immediately conveys the core action. There is no redundant wording or filler; every word contributes to the purpose. This is appropriately sized for a simple getter tool.

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

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

Given the tool's simplicity (2 required parameters, no output schema or annotations), the description is mostly sufficient for an agent to understand its basic function. However, the lack of behavioral details (e.g., not-found behavior) and absence of any guidance on return format means the description is not fully complete, especially in the absence of annotations and output schema.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the parameters. It mentions 'by its Id,' which relates to record_id, but it does not clarify what table_id is for or how the two IDs interact. The parameter names are self-explanatory, but the description adds little semantic value beyond the schema.

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

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

The description 'Get a single record by its Id' is specific with a clear verb ('get'), resource ('record'), and scope ('single by Id'). This distinguishes it from siblings like list_records (which lists multiple) and create/update/delete records, making the tool's purpose unambiguous.

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

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

The description implies usage when a specific record ID is known, but it does not explicitly contrast with list_records or provide criteria for when to choose this tool over alternatives. No exclusions or alternative references are given, so usage guidance is only implicit from the verb and parameter names.

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

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It does explain what the tool returns and notes it is used for field validation, but it does not disclose potential errors, rate limits, or confirm read-only behavior beyond the verb 'Get'. It adds meaningful context but falls short of full transparency.

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

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

The description is two sentences: the first defines the tool's purpose with a detailed breakdown of content, and the second gives actionable usage advice. There is no redundancy or filler; it is front-loaded and 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?

For a single-parameter tool with no annotations and no output schema, the description provides a complete picture: what the schema contains, how to use table_id (via schema), and why to call it before mutations. This is sufficient for selection and invocation.

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

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

The schema description for table_id ('Table ID, from list_tables') already covers the parameter fully, giving 100% schema description coverage. The tool description does not add extra meaning about the parameter's format or usage, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Get full schema for a table' and enumerates exactly what the schema includes (fields/columns, types, options, relational fields with linkFieldId). This is a specific verb+resource formulation that distinguishes it from siblings like list_tables or get_record.

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 creating/updating records so you know valid field names and link field ids.' This provides clear contextual guidance for when to use it. It does not mention when not to use it or point to alternatives, but none are obvious for schema retrieval, so the context is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core linking action but does not mention whether existing links are appended or replaced, how duplicate links are handled, any permission requirements, or potential side effects. This is a significant transparency gap for a mutating operation.

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

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

The description is a single, direct sentence that front-loads the verb 'Link' and includes a helpful parenthetical example. Every word adds value, with no redundancy or extraneous 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?

Given the tool's moderate complexity (4 required parameters, no output schema, no annotations), the description provides a clear core function and example but lacks important behavioral details such as whether links are additive or replace existing links, and what the return value is. Since no output schema exists, the description could have addressed response behavior to be more complete.

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

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

The input schema covers 75% of parameters with descriptions, and the description adds overall context by explaining that record_id is the target record and related_record_ids are records to attach. However, it does not add new details about parameter syntax or constraints beyond what the schema already provides, so it meets but does not exceed the baseline.

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

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

The description clearly states the action ('Link'), the objects ('one or more existing records'), the target ('a given record'), and the mechanism ('through a relational (Links) field'). The example 'attach child records to a parent' further clarifies the intended use, distinguishing this from siblings like unlink_records and list_linked_records.

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

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

The description implies when to use the tool (to create relational links) and provides a concrete example, but it does not explicitly state when not to use it or mention alternative tools such as unlink_records or list_linked_records. The usage context is implied rather than explicitly contrasted with siblings.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds useful context about API token visibility and platform-specific parameter behavior, but it does not describe the return format, pagination, or potential errors. This is a modest disclosure for a simple list tool.

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

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

The description is two sentences, front-loaded with the primary purpose, and every word contributes value. No redundant or vague phrasing.

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

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

For a tool with a single optional parameter and no output schema, the description covers the essential purpose and usage context. However, it leaves minor ambiguity about whether workspace_id is required on Cloud when multiple workspaces exist, and it does not hint at the return structure. These are minor gaps for such a simple tool.

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

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

Although the schema already documents the workspace_id parameter well (100% coverage), the description adds practical meaning by explaining when to pass it and when to omit it (Cloud vs. self-hosted). This goes beyond the schema's static description.

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

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

The description clearly states the tool's function: 'List NocoDB bases (projects) visible to this API token.' It uses a specific verb and resource, and the mention of 'bases (projects)' distinguishes it from sibling tools like list_workspaces and list_tables.

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

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

The description provides clear context for when to pass the workspace_id parameter: 'on NocoDB Cloud if you have multiple workspaces' and to omit it for self-hosted instances. It doesn't explicitly name alternative tools, but for a list operation the usage context is sufficiently clear.

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

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

No annotations are present, so the description must carry full behavioral burden. It does not disclose whether linked record IDs or full records are returned, does not mention pagination, and does not clarify ordering or other behavioral aspects.

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

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

The description is a single sentence, concise, and front-loaded with the action. Every word is purposeful with no redundancy.

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

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

With five parameters, no output schema, and no annotations, this tool requires more context. The description omits return shape, pagination behavior, and usage tips, leaving the agent under-informed for correct invocation.

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

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

Schema description coverage is only 20% (only link_field_id is described). The tool description adds no explicit explanations for table_id, record_id, limit, or offset, and does little to compensate for the low schema coverage beyond implying record_id from 'given record'.

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

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

The description clearly states the tool lists records linked to a given record via a relational Links field. It uses a specific verb and resource and distinguishes from siblings like list_records or link_records by focusing on existing links.

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

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

No guidance is provided on when to use this tool versus alternatives such as list_records or get_record. The description only states what it does, not the context or 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 provided, the description carries the full burden for behavioral disclosure. It states the core capabilities but does not explicitly confirm the operation is read-only, describe the return format, or mention any side effects. While 'list' implies a read operation, the lack of an output schema and explicit behavioral notes limits transparency.

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

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

The description is a single sentence of 14 words, efficiently conveying the primary purpose and key optional features without redundancy. It is front-loaded with the verb and resource, making it immediately scannable.

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

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

Given the tool's moderate complexity (7 parameters) and the absence of an output schema, the description plus the comprehensive parameter descriptions provide a fairly complete picture for an agent to invoke the tool correctly. However, explicitly stating that it returns a list of record objects or confirming the read-only nature would enhance completeness.

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 provides comprehensive descriptions for all 7 parameters, including examples for 'sort' and 'where', and the 'table_id' description references list_tables. The description itself adds no additional parameter semantics beyond what the schema already covers, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'List' with the resource 'records from a table', clearly distinguishing from sibling tools like list_tables (which lists tables) and get_record (which fetches a single record). It also enumerates key optional capabilities (filtering, sorting, field selection, pagination), leaving no ambiguity about the tool's function.

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 usage for retrieving table records with flexible options, but it does not explicitly state when to choose this over alternatives like list_linked_records or count_records. No exclusions or alternative tool names are mentioned, so the agent must infer from context.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It mentions output fields but does not state that the operation is read-only, any permissions required, or behavior on invalid base_id. The word 'List' implies a read operation, but this is not explicitly confirmed.

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

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

The description is a single, focused sentence that immediately states the action and scope, with no redundant words. It is front-loaded with the core purpose and includes the key output fields without unnecessary elaboration.

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?

This is a simple, one-parameter listing tool. The description specifies the return fields (id, name, type), which is important since there is no output schema. It is complete enough for an agent to understand the scope and result, though it lacks explicit edge-case handling (e.g., invalid base_id) or read-only guarantees, which would make it truly comprehensive.

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

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

Schema description coverage is 100% for the single parameter (base_id), and the description adds the context that this parameter identifies the base to list tables from. However, no additional semantic details are provided beyond what the schema's 'Base ID, from list_bases' already states, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('tables within a NocoDB base'), and specifies the output fields (id, name, type). This clearly differentiates from sibling tools like list_bases (bases) and list_records (records).

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 usage by stating 'within a NocoDB base' and the base_id parameter is described as 'from list_bases', suggesting a prerequisite. However, no explicit guidance is provided on when to choose this tool over alternatives or what exclusions apply, leaving usage context mostly implicit.

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 adds context about token-visible scoping and cloud-only deployment, which is useful. However, it does not explicitly state read-only nature or return format, leaving some gaps for a simple list operation.

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

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

The description is two sentences: the first front-loads the core action, and the second provides a critical usage caveat. No word is wasted, and the structure is clear and scannable.

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

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

Given the tool's low complexity (0 params, no output schema), the description covers the essential context: purpose, token scoping, deployment relevance, and an explicit alternative. It doesn't spell out the return structure, but 'List X' strongly implies an array of X, so the completeness is adequate.

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 the baseline for this dimension is 4. The description doesn't need to explain parameters, and it doesn't add any conflicting or irrelevant information. It correctly implies that no arguments are needed.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'List NocoDB workspaces visible to this API token.' It also differentiates from the sibling tool list_bases by noting the cloud-only relevance, making it unmistakable what this tool does.

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

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

The description explicitly explains when to use this tool vs. alternatives: 'Only relevant on NocoDB Cloud; self-hosted OSS instances typically don't use workspaces — call list_bases directly instead.' This gives a clear context and names the alternative, satisfying the dimension.

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, and the description only states the core action ('Remove a link') without disclosing side effects, reversibility, permission requirements, or behavior for non-existent links. As a mutation tool, more transparency is needed.

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

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

The description is a single, focused sentence that states the action, target, and scope without unnecessary words. It front-loads the verb and resource.

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

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

Given no annotations and no output schema, the description should cover usage context, return behavior, and edge cases. It lacks any mention of when to use, what happens after unlinking, or whether the operation is idempotent. The presence of sibling tools like link_records further emphasizes the need for distinguishing guidance.

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

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

The schema already provides descriptions for 3 of 4 parameters (75% coverage). The description adds context that the operation works via a relational (Links) field and supports multiple related records, which aids understanding of link_field_id and related_record_ids. However, it doesn't fully compensate for the undocumented table_id.

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

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

The description uses the specific verb 'Remove' and explicitly names the resource ('a link between a record and one or more related records through a relational (Links) field'). This clearly distinguishes it from siblings like link_records (which adds links) and delete_records (which removes records).

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

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

No explicit usage guidance or alternatives are mentioned. The inverse operation (link_records) is a sibling tool, but the description doesn't tell the agent when to choose unlink_records over link_records or other mutations. The intended use case is implied by the verb but not articulated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'update' which implies mutation, but provides no details on permissions, reversibility, error behavior, or whether updates are partial or full replacements. This is a significant gap for a mutation tool.

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

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

The description is a single concise sentence, front-loaded with the primary action ('Update one or more existing records'). It is efficient, though it could have added more value with a bit more detail without being verbose.

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

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

Given the tool's mutation nature and lack of annotations or output schema, the description is insufficient. It does not clarify return value, idempotency, batch behavior, or failure scenarios. The provided context signals show minimal schema coverage, and the description does not compensate.

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 description repeats the Id requirement already present in the records parameter schema, adding no new meaning. It completely fails to describe table_id, which has no schema description, leaving a 50% coverage gap unaddressed.

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

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

The description clearly states the tool updates existing records, using a specific verb ('Update') and resource ('existing records'). It distinguishes itself from sibling tools like create_records and delete_records by focusing on modification of existing data.

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 modifying existing records, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions. The note about including Id is a requirement, not a usage context.

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