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

With no annotations, the description carries the full behavioral burden, and it delivers important lifecycle context: a hard sunset date (2026-07-08), V1 API sunset cause, no workaround, and removal in v2.0.0. It does not cover auth requirements or response behavior, but the deprecation disclosure is genuinely valuable and non-obvious.

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 critical fact (DEPRECATED) is front-loaded, and every sentence concerns the sunset, which is the dominant concern. There is mild redundancy — the removal/cleanup and the 2026-05 changelog note restate the same idea — but nothing is wasted on irrelevant content.

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

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

For a mutation tool with no annotations and no output schema, the description thoroughly covers the deprecation but omits what the tool actually does to a note and what it returns. An agent knows the tool is doomed but must still infer its core effect, leaving a completeness gap.

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

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

Schema description coverage is 100% and both parameters (noteId, content) are documented in the schema itself. The description adds nothing about parameter meaning, so the baseline 3 applies.

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

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

The description identifies the resource ("note-comments endpoint", "comment feature") but never states the actual action — that it adds a comment to a note. The entire text is devoted to deprecation, so the core verb+resource purpose is left to inference from the tool name, and no sibling (e.g. create_note, update_note) is contrasted.

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

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

It gives explicit when-to-use and when-not guidance: "Continue using only if comments are critical AND you have a contingency for sunset," plus "No workaround available." It even addresses the alternative (V2 has no equivalent), though it does not route to any concrete sibling tool because none exists.

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 behavioral burden. It states the fields must match configuration schemas but says nothing about permissions/auth, validation failure behavior, what the created entity response looks like, or effects on relationships. For a mutation tool with zero annotation coverage this is a significant gap.

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

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

Three short sentences, front-loaded with the core action and the prerequisite immediately after. No filler, though the final sentence repeats the get_entity_configurations advice already given.

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

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

Covers the creation action and the configuration prerequisite, but for a multi-entity-type mutation tool with nested relationship objects and no annotations or output schema, it leaves out validation behavior and return semantics that an agent would need.

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

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

Schema description coverage is 100%, so the schema already documents type, fields, and relationships. The description reinforces the fields-vs-configuration relationship but adds no syntax, format, or constraint details beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a new Productboard entity'), which is distinct from update_entity/delete_entity siblings. It doesn't explicitly contrast with siblings like update_entity, but the create action is unambiguous.

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

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

Gives an explicit prerequisite and ordering: 'Call get_entity_configurations first to discover available fields for the entity type.' This is actionable guidance, though it doesn't mention when to choose this over alternatives or what happens on invalid input.

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 behavioral burden. It does not state whether duplicate relationships are rejected or idempotent, whether required permissions apply, what happens to an existing relationship of the same type, or whether the operation is reversible via delete_entity_relationship.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though its brevity is partly a symptom of missing information rather than disciplined trimming.

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

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

For a mutation tool with no annotations and no output schema, this is insufficient. The description should at minimum indicate whether it returns the created relationship, how conflicts are handled, and how it relates to sibling creation tools like set_entity_parent.

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

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

Schema description coverage is 100%, with each parameter (entityId, targetId, type) documented directly in the schema including the enumerated relationship types. The description adds no meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ('Create a relationship') and scopes it to Productboard entities, so the agent knows what the tool does. However, it does not distinguish itself from close siblings such as set_entity_parent (which also creates a parent relationship) or create_note_relationship, leaving ambiguity about which creation tool to pick.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from the description whether to use this versus set_entity_parent for a 'parent' relationship, or versus create_note_relationship for note-backed entities.

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 behavioral burden, yet it only covers a workflow pointer. It says nothing about required permissions, side effects, whether the note is immediately visible, or error conditions for a mutation tool. The 'opportunity notes cannot be created via API' constraint lives only in the schema, not the description.

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

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

Two short sentences with the action front-loaded and the prerequisite second. No filler; every clause 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 nested relationships object and mutation nature are non-trivial, and with no annotations and no output schema the description should disclose more about permissions, effects, and return shape. The prerequisite guidance is useful but leaves the behavioral picture incomplete.

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

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

Schema description coverage is 100%, so the schema already documents type, fields, and relationships, including the enum and the 'name is required' rule. The description adds the pointer to get_note_configurations for field discovery, which is modest value over the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Create a new Productboard note (insight)'. This is clearly distinguishable from the entity and relationship tools, though it doesn't explicitly contrast itself with create_entity or note-creation alternatives.

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

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

Provides an explicit prerequisite workflow: 'Call get_note_configurations first to discover available fields and note types'. This tells the agent how to prepare, though it offers no when-not-to-use guidance or alternatives to create_note.

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

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

With no annotations, the description must carry the behavioral load. It discloses the important destructive trait: for customer relationships, the existing link is replaced. However, it doesn't mention permissions, reversibility, or what happens to entity ('link') relationships when re-linking.

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

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

Two tight sentences, front-loading the action and immediately following with the critical replace behavior. No wasted words.

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

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

For a mutation tool with 4 parameters, no annotations, and no output schema, the description covers purpose and a key destructive trait but omits permissions, error conditions, or return value. It is minimally adequate but leaves gaps given the lack of structured behavioral hints.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including the enum for 'type'. The description adds the concept of customer vs. entity linking but doesn't clarify the targetType parameter or noteId usage beyond what the schema provides. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb (Link) and resource (a Productboard note) with the target scope (customer/entity). It clearly distinguishes itself from siblings like create_entity_relationship and set_note_customer by describing the linking action and its replace semantics.

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 it (to link a note to a customer or entity) and notes that customer links are replaced, but it doesn't explicitly say when to prefer this over set_note_customer or a generic relationship tool. Usage is inferable but not directed.

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 burden and does well: it discloses permanence, cascade deletion of child entities, and irreversibility. It omits authorization requirements and any rate-limit or confirmation expectations, keeping it short of a 5.

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

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

Two sentences, zero filler, and the critical warning (cascade + irreversible) is front-loaded immediately after the purpose. Every clause 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 destructive tool with no annotations and no output schema, the description covers the essential risk profile an agent needs before calling. Only the absence of auth/permission context keeps it from being fully complete.

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

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

Schema coverage is 100%, so the single 'id' parameter is fully documented as an 'Entity UUID to delete'. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Permanently delete') and resource ('Productboard entity'), which cleanly separates it from the create/update/get entity siblings and from delete_note / delete_entity_relationship. The scope is unambiguous.

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

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

The destructive, irreversible nature implies 'use only when removal is intended', but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., permissions, whether children must be detached first), and no pointer to alternatives such as delete_entity_relationship.

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 behavioral burden for a destructive delete operation. It does not disclose irreversibility, permission requirements, or the effect on dependent relationships, saying only that it 'removes' the link.

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

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

Two tight sentences with the action front-loaded and no filler; every clause carries 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?

Schema coverage makes the parameters complete, but for a destructive tool with no annotations and no output schema the description should explain reversibility and failure behavior, which it omits entirely.

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

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

Schema description coverage is 100%, so the schema already documents entityId, type, and targetId. The description names the type and target but omits the entityId and adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb (Remove) plus resource (relationship from a Productboard entity), which cleanly separates it from create_entity_relationship and get_entity_relationships. It is clear but does not explicitly name or contrast with those siblings.

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

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

It states the required inputs but offers no when-to-use guidance, no prerequisites (auth/permissions), and no mention of the create/set alternatives. Usage is only implied by the verb.

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

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

With no annotations, the description carries the full burden. It does disclose the most important trait — the operation is permanent and irreversible — but says nothing about required permissions, what happens to attached relationships or comments, or error behavior when the note is absent.

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

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

Two short sentences, front-loaded with the action and immediately followed by the critical irreversibility constraint. No filler text.

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

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

For a destructive, irrecoverable tool with no annotations and no output schema, the description covers the essential warning but omits side effects (relationships, comments, customer links) and failure modes. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented as the note UUID in the schema. The description adds no format, sourcing, or lookup guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Permanently delete a Productboard note'), which cleanly separates it from siblings like delete_entity or delete_note_relationship by naming the target resource. It does not explicitly name an alternative sibling, but the resource noun makes intent 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?

There is no guidance on when to reach for this tool versus alternatives such as update_note or delete_note_relationship, nor any stated prerequisites. The irreversibility warning hints at caution but does not tell the agent when use is appropriate.

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 at all, the description carries the full burden for a destructive mutation, yet it discloses nothing about reversibility, required permissions, or side effects on the related customer/link entity. 'Remove' conveys deletion but no behavioral detail beyond that.

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

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

A single short sentence with the action front-loaded and no filler. It is efficient, though extremely terse for a destructive operation.

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

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

For a required-3-parameter destructive tool with no annotations and no output schema, the description is too thin: it omits prerequisites, irreversibility, and success/failure behavior. The schema covers the inputs, but nothing covers the operation's consequences.

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%: noteId, targetId, and the targetType enum are all documented in the schema, so the baseline of 3 applies. The description adds no extra parameter meaning (e.g. which relationship types exist or what a 'link' target means) 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?

States a specific verb ('Remove') and resource ('a relationship from a Productboard note'), which clearly separates it from create_note_relationship and get_note_relationships among the siblings. It stops short of naming those siblings or the relationship types, so it is clear but 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.

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

There is no explicit when-to-use, when-not-to-use, or alternative guidance. The verb implies a deletion context, but nothing tells the agent when this is appropriate versus updating or recreating the relationship.

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 behavioral burden. 'Get' self-evidently signals a read-only operation and it discloses return content ('full entity data including fields and relationships'), but it omits permissions, error behavior for unknown UUIDs, and any rate-limit 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?

Two short sentences with zero filler; the identification mechanism (UUID) is front-loaded before the return-value note. Every clause 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?

With no output schema, the description partially compensates by noting the return includes fields and relationships. Both parameters are covered by the schema. It is nearly complete for a simple single-resource fetch, with only error/permission behavior left unstated.

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

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

Schema coverage is 100%, so both the required 'id' UUID and the 'fields' control parameter are fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('a single Productboard entity by its UUID'), which naturally separates it from list_entities and search_entities by scope. It does not explicitly name those siblings, but the 'single/by UUID' qualifier gives an agent enough to distinguish it.

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 'by its UUID' phrasing implies the tool is used when the caller already holds an identifier, distinguishing it from search/list. However, no explicit when-to-use guidance or named alternatives (search_entities, list_entities) are given, leaving routing to inference.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is a discovery/read operation and what data it returns, but does not state whether it is safe/non-mutating, has side effects, requires auth, or provides caching. A 3 reflects adequate-but-incomplete behavioral disclosure for a no-annotation 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?

Three short sentences, front-loaded with the core capability, followed by the usage trigger and the optional filter. No waste; every sentence contributes.

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 a simple single-parameter discovery endpoint with no output schema. The description covers purpose, usage timing, and parameter behavior sufficiently for an agent to call it. Minor gap: it does not describe the shape of returned field metadata beyond a parenthetical list, which for a discovery tool would help the next step.

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 only one parameter at 100% schema coverage, the schema already fully documents 'entityType' including the enum values and the omission behavior. The description restates the optional filter ('Optionally filter by entityType') without adding syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Discover available entity types and their fields') and enumerates what is returned (field names, types, options, lifecycle operations). Clearly distinguishable from siblings like get_note_configurations and get_entity, which fetch different resources.

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

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

Explicit when-to-use: 'Call this before creating or updating entities to learn what fields are available.' It names the relevant sibling operations (create/update) as the trigger, so the agent knows exactly when this tool precedes others.

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 behavioral burden. It discloses that all relationship types are returned and lists examples, implying a read-only operation, but it does not mention permissions, pagination, rate limits, or response shape.

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

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

Two sentences, front-loaded with the core purpose and followed by optional filter information. No filler or redundancy; 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 read-only tool with 3 parameters all documented in the schema and no output schema, the description covers purpose, scope, and filtering. It is largely complete, though it omits pagination or limit behavior that an agent might need for a listing operation.

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

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

Schema description coverage is 100%, so all three parameters (type, entityId, targetId) are already documented in the schema. The description's mention of filtering by relationship type or target duplicates the schema without adding syntax, format, or constraint details. Baseline 3 is appropriate.

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

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

States a specific verb ('Get') and resource ('relationships') for a Productboard entity, and enumerates relationship kinds (parent, children, links, blocking). It distinguishes itself from get_entity by focusing on relationships rather than the entity itself, though it does not name a sibling alternative explicitly.

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

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

The description says it can optionally filter by relationship type or target, which implies a usage pattern. However, there is no explicit guidance on when to use this tool versus alternatives like get_entity, list_entities, or the relationship-mutating siblings, nor any prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read, but it never confirms read-only semantics, says nothing about behavior for a missing/invalid UUID, permissions, or response shape.

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

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

One short sentence with the resource and lookup key front-loaded and no filler. It is efficiently sized, though extremely terse for a tool with zero supporting annotations.

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 trivial single-fetch tool with no output schema and complete parameter documentation, little is strictly required. Still, with no annotations and no output schema, the description leaves the read-only nature and failure behavior entirely unstated.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as 'Member UUID' in the schema. The description's 'by UUID' adds mild emphasis but no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('Productboard workspace member') and scopes it to a single item 'by UUID', which implicitly separates it from list_members. It does not explicitly name the sibling alternative, so it stops short of a 5.

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

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

The phrase 'by UUID' implies you need an identifier in hand, which is decent implied usage context, but the description never states when to use this versus list_members or get_member_activities, nor any preconditions.

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 exist, so the description carries the full burden. It usefully discloses the shape of the return (daily per-member counts) which helps since there is no output schema, and 'Retrieve' implies a read-only operation. However it says nothing about pagination behavior despite pageCursor/limit parameters, nor about rate limits or permissions.

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

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

Two short sentences, front-loaded with what the tool does followed by what it returns. No filler, though the second sentence slightly restates the first's resource focus.

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

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

For a four-parameter read tool with no annotations and no output schema, the description partially compensates by describing the return content, but omits pagination semantics (pageCursor interplay) and scoping/permission context, leaving gaps an agent would need.

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

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

Schema description coverage is 100%, and all four parameters (limit, dateFrom, dateTo, pageCursor) are documented in the schema with defaults, ranges and ISO 8601 format examples. The description adds no parameter-level detail, so baseline 3 applies.

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

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

Names a specific verb ('Retrieve') and resource ('member activity metrics') and describes the returned payload (daily activity data with feature/note/board creation counts). It is clear what the tool does, though it never explicitly contrasts itself with the sibling get_member or list_members tools.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as get_member or list_members. Usage is only implied by the verb 'Retrieve'.

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 behavioral burden. The word 'Get' implies a read-only, non-mutating operation, which is the key trait here, but the description says nothing about permissions, behavior when the UUID is not found, or what the response contains.

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

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

A single front-loaded sentence with the verb, resource, and lookup key in immediate succession. Every word earns its place with zero 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 simple single-item getter with no output schema and no annotations, the description is minimally adequate but omits what the caller receives and how lookup failures behave. It gives just enough to invoke the tool, not enough to fully anticipate its behavior.

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

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

With one parameter and 100% schema description coverage, the schema already documents 'id' as 'Note UUID'. The description's 'by its UUID' confirms the parameter's role but adds no syntax, format, or sourcing detail beyond the schema. Baseline 3 applies 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.

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

States a specific verb ('Get') and resource ('Productboard note') with the identifying mechanism ('by its UUID'). However, it does not distinguish itself from the sibling get_note_v1, which an agent could easily confuse with this tool, nor does it clarify its relationship to list_notes.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as list_notes, list_all_notes, or get_note_v1. The phrase 'a single note by its UUID' implies retrieval-by-id rather than listing, but the agent must infer this with no stated exclusions.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It implies a read-only discovery call and gives useful sequencing context, but says nothing about the shape or stability of the returned configuration data, which matters for a tool with no output schema.

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

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

Two short sentences, purpose first and usage second, with no filler. Every clause 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 no-arg-except-filter discovery tool with full schema coverage, the definition is nearly sufficient; 'and their fields' hints at the return content, though a note on what a configuration object contains would close the last gap.

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

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

Schema description coverage is 100% and the single optional noteType enum is fully documented in the schema, so the description adds no syntax or format detail beyond it. Baseline 3 applies 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.

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

States a specific verb+resource: discover available note types and their fields. The enumerated types (simple, conversation, opportunity) make the scope concrete, though it never contrasts itself with the similarly named sibling get_entity_configurations.

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

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

Explicitly states the condition that selects it: 'Call this before creating or updating notes.' That is clear ordering guidance, but no when-not or alternatives are given, so it stops short of a full 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the broad shape of the return data but says nothing about permissions, pagination, ordering, or what happens for a note with no relationships.

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

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

A single front-loaded sentence with no filler, immediately naming the verb, the resource, and the kind of data returned.

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 single-parameter read tool with no output schema, the description is minimally adequate: it indicates the returned relationship data. However, with zero annotations it could reasonably state the read-only nature or response shape more explicitly.

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 noteId parameter ('Note UUID'), so the schema already documents the input fully. The description adds no extra parameter meaning, making the baseline 3 appropriate.

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

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

States a specific verb ('Get') and resource ('relationships for a Productboard note') and clarifies the returned data ('linked customers, entities, etc.'). It is distinguishable from write siblings like create_note_relationship, though it does not explicitly contrast itself with the near-named get_entity_relationships.

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

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

There is no explicit when-to-use guidance, no mention of alternatives such as get_entity_relationships or list_notes, and no prerequisites. Usage is only inferable from the tool name and the word 'relationships'.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that the tool now delegates to the v2 endpoint, lists the V1-only fields that are no longer returned (followers[], embedded comments[], features[].importance), documents a field rename (displayUrl → links.html), and gives a deprecation/removal horizon. This is exactly the behavioral context an agent would otherwise have to discover by failing.

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?

Information is front-loaded with the DEPRECATED marker and the recommended replacement, which is the right ordering. It is fairly dense with migration detail, but nearly every clause (field removals, field rename, removal date) is actionable for an agent and not 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 deprecated alias of a single-parameter lookup with no output schema, the description covers everything an agent needs: what it maps to, what responses omitted, how fields map, and when it disappears. Nothing material is missing.

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

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

There is a single parameter (id) with 100% schema description coverage, so the schema already documents it as a Note UUID. The description adds nothing about the id parameter itself, only the endpoint path shape, so the baseline of 3 applies.

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

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

The description states a specific operation (retrieve a note by id) and immediately frames it as an alias for the sibling get_note, so an agent can tell exactly what it does and how it differs. It also names the underlying endpoint (v2 GET /notes/{id}), which reinforces the resource.

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 the tool is DEPRECATED and directs the agent to use get_note instead, and explains the only reason to keep using it (backwards compatibility during V1→V2 migration). It also states the removal timeline, giving an unambiguous when/when-not condition.

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

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

With no annotations, the description carries the full burden and does so: it discloses auto-pagination (~100/page), a hard 5000-note safety cap, default filtering behavior, and concrete v2 response-shape details including what no longer exists (followers, comments, totalResults, features[].importance) and the migration path for displayUrl and linked features.

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

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

Front-loaded with the core operation, pagination and safety limit, then defaults, then response shape. It is dense but each sentence conveys actionable information; the v1→v2 migration notes are long but relevant for correct data interpretation.

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

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

With no output schema, the description compensates by describing the v2 note shape and the relationship/migration caveats, which is exactly what an agent needs to consume results. Minor gaps remain around rate limits or ordering, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters, including defaults and the members:pii:read scope for ownerEmail. The description largely restates the archived/processed defaults and adds no syntax or interpretation beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Bulk-fetch Productboard notes via V2 API') with an explicit scope qualifier ('bulk-fetch') that hints at a paginated list operation. It does not explicitly contrast itself with the sibling list_notes or search_notes, so an agent still has to infer which listing tool to pick.

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

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

Gives clear defaults (processed+unprocessed, non-archived) and tells the agent how to include archived notes. It also names an alternative tool with a condition ('use get_note_relationships per note if you need them'). It stops short of distinguishing this tool from list_notes or search_notes.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses pagination behavior: 'Returns paginated results — use pageCursor from response to get next page.' However, it omits other behavioral traits such as whether the operation is read-only, any permission requirements, or what the response structure looks like beyond pagination.

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 tightly written sentences with zero waste. It front-loads the core purpose and then adds filtering and pagination details, making it easy to scan.

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

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

For a nine-parameter list tool with no output schema and no annotations, the description covers the essential context: purpose, supported filters, and pagination mechanics. It is missing details about the return format and default field behavior, but it provides enough for an agent to call the tool correctly given the complete 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 100%, so all nine parameters are already documented in the input schema. The description adds a summary of filterable fields (name, owner, status, archived, parent) and mentions pageCursor, but this is largely redundant with the schema. The baseline of 3 applies 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.

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

The description states a specific verb and resource: 'List Productboard entities of a given type.' It also lists the supported filters, making the tool's function clear. However, it does not differentiate this tool from siblings like search_entities or get_entity, so it falls short of the top score.

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 ('List ... entities of a given type') but provides no explicit when-to-use guidance, no alternatives, and no exclusions. It does not say when to prefer this over search_entities or get_entity, leaving the agent to infer the appropriate context.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state that results are paginated, what the default page size is, whether this is a read-only safe call, or what permission level is required for listing members.

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

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

Two short sentences with the core action front-loaded and the optional refinement second. No wasted words 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 simple three-parameter list tool with full schema coverage and no output schema, the description is minimally sufficient. It leaves gaps around pagination behavior and how this tool relates to the singular get_member sibling.

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

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

Schema description coverage is 100%, so all three parameters (role, limit, pageCursor) are already documented in the schema, including the enum values and default. The description's mention of the role filter adds nothing beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('List Productboard workspace members'), and the optional role filter narrows scope. It does not explicitly distinguish itself from the sibling get_member (singular) or get_member_activities, so sibling differentiation is left to inference.

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?

'Optionally filter by role' hints at one usage path but gives no when-to-use guidance, no mention of pagination follow-up, and no routing advice against get_member or get_member_activities.

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

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

With no annotations, the description carries the full burden and discloses important behavioral traits: default filtering, sorting order, archived inclusion rules, and the v2 quirk that archived notes always report processed=false. It does not cover auth scope requirements (mentioned only in schema for ownerEmail/creatorEmail), rate limits, or return format, but it is substantially transparent for a 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 front-loaded with the core purpose, then efficiently covers sorting, defaults, and the archived quirk. Every sentence earns its place, and there is no redundant or filler content.

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 12-parameter list tool with no output schema or annotations, the description provides essential context on default behavior, sorting, and the tricky archived/processed interaction. It omits some details such as expected response shape and pagination usage beyond the cursor parameter, but the schema covers individual parameter meanings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining the default archived/processed behavior and the interaction between archived=true and omitting processed, which clarifies how to use those parameters together.

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 (List) and resource (Productboard notes/insights) and notes pagination, sorting, and filters. It does not, however, explicitly distinguish this tool from siblings such as list_all_notes or search_notes, so it falls short of full sibling differentiation.

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

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

The description clearly explains the default behavior (processed + unprocessed, non-archived) and how to include or fetch only archived notes, including the v2 quirk. It does not mention when to prefer this tool over alternatives like search_notes or list_all_notes, so it lacks explicit exclusions/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 full burden and does well: it discloses the return shape (v2 note with links.html, equivalent to v1 displayUrl), the fallback resolution algorithm for numeric IDs (scan up to 500 most-recent notes, ~5 pages), and that archived notes are included. It does not state failure behavior when a numeric ID is older than the scan window or any permission requirements, which keeps it short of a 5.

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

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

Three dense sentences, front-loaded with purpose and accepted formats, followed by return shape and then the resolution caveat. Every clause carries information an agent needs; nothing is padding.

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

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

For a single-parameter read tool with no output schema, the description covers input formats, return contents, and the scan limitation, which is enough to invoke it correctly. It omits not-found/error behavior and any access requirement, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% for the single identifier parameter, so the baseline is 3. The description goes beyond the schema by tying parameter form to behavior: numeric IDs trigger a bounded page scan of up to 500 recent notes, which the schema does not say. That is genuine added meaning over the structured field.

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

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

The description names a specific verb (resolve) and resource (Productboard note) and immediately scopes the tool's differentiator: it accepts any identifier form (UUID, numeric ID, URL, deep link). This implicitly separates it from get_note/get_note_v1, which take a canonical ID, but no sibling is named explicitly, so the differentiation must be inferred.

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 rather than stated: an agent can infer 'use this when you have a loose or unknown identifier' from the accepted-format list, and the numeric-ID scan note hints when the lookup is expensive. However, there is no explicit when-not-to-use guidance or named alternative such as get_note for known UUIDs, so routing requires inference.

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 disclosure burden. It does disclose a real behavioral caveat beyond structured data – the `name` filter is silently ignored upstream (with a verification date) – which is exactly the kind of non-obvious trap an agent needs. It stops short of covering auth requirements, rate limits, or the read-only nature of the operation, so it is not fully complete for a zero-annotation 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?

Three sentences, front-loaded with the core capability, then the filter surface, then the routing caveat. Efficient and well-ordered, though the name-filter guidance is stated twice (in the description and again in the schema), a minor 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?

Nine parameters, no output schema, and no annotations – the description covers the filter scope, the important upstream defect, and the alternative tool, which is enough for correct invocation. Return shape and pagination semantics are only implied by the `pageCursor` field, leaving a small gap for a search tool.

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

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

Schema description coverage is 100%, so every one of the nine parameters is already documented at the field level (including the `name` warning). The description's parameter content largely restates the schema's filter list, so a 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 opens with a specific verb+resource ("Search Productboard entities") and enumerates the filter surface (types, statuses, owners, parent, archived, IDs), which maps directly to the schema. It also names the sibling it is not (list_entities), letting an agent distinguish the two without opening either schema.

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

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

It gives explicit routing guidance: "For name-based search use list_entities" and explains why (the `name` filter here is forwarded upstream but ignored). This is a clear when-to-use / when-to-use-something-else statement rather than implied usage.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the V2/V1 routing logic, the sunset date for the V1 path, how to distinguish response shapes (apiVersion, displayUrl vs links.html), and that archived is hidden by default and only honored on V2. This is unusually rich behavioral context beyond any structured field.

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?

Dense but front-loaded: purpose first, then routing, then response-shape divergence, then the archived default. Every sentence carries load, though the response-shape sentence is somewhat cramped and could be tightened.

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 16-parameter tool with no output schema and no annotations, the description compensates by explaining the two possible return shapes and the routing that determines them, plus the key default behavior. Nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that `last` is auto-translated to V2 updatedAt.from and no longer forces V1, and that `term`/multi-`allTags` force the fallback path. These are semantic consequences the schema descriptions only partially capture.

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

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

States a specific verb and resource ('Search Productboard notes (insights)') and immediately scopes it against siblings by describing search semantics rather than listing. An agent can tell this apart from list_notes/get_note without opening the schema.

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

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

Gives clear conditional guidance for internal routing (V2 default; V1 fallback only when term is set or allTags has 2+ values) and states the archived default with how to override it. It stops short of naming when to prefer this over siblings like list_notes or list_all_notes, so it is clear context without explicit alternative routing.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the operation uses PUT and replaces any existing parent relationship, but it does not cover permissions, side effects, reversibility, or what happens if the parent is invalid.

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

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

The description is two short sentences with no wasted words. The core purpose is front-loaded, followed immediately by the replacement behavior.

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 mutation with full schema descriptions and no output schema, the description is nearly complete: it states the operation and the replace semantics. It leaves minor gaps around authorization and error behavior, but no annotation or output schema requires further explanation.

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

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

Schema coverage is 100%, and both parameters are documented in the schema as UUIDs for child and new parent. The description adds no parameter meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb+resource: it sets or replaces the parent of a Productboard entity. This is clearly distinguishable from sibling tools like create_entity_relationship or update_entity because it directly names the parent-linking operation.

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 implies usage by saying 'Set or replace the parent,' which tells the agent this is the tool for assigning a parent. However, it does not explicitly say when to choose this over alternatives such as create_entity_relationship, nor does it state any exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden. 'Set or replace' usefully discloses that an existing relationship is overwritten rather than added alongside, which is real behavioral information. However, it says nothing about required permissions, what happens to a previously linked customer, or error behavior when the type is invalid.

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

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

Two short sentences with the action and the constraint front-loaded; nothing is wasted and no filler is present.

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 three-parameter mutation tool with no annotations and no output schema, the description covers the purpose and the target-type constraint but omits mutation side effects, permission requirements, and confirmation of what the call returns. It is minimally viable rather than complete.

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

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

Schema description coverage is 100% and the enum on customerType is already declared, so the description's 'user or company' statement largely restates structured data. It adds no format, ordering, or side-effect detail for noteId or customerId beyond what the schema provides.

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

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

The description pairs a specific verb ('Set or replace') with a precise resource ('the customer relationship on a note'), so an agent knows exactly what is mutated. It does not name a sibling such as create_note_relationship or delete_note_relationship to disambiguate, but the scope is unmistakable.

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?

'Only accepts user or company targets' is a parameter constraint, not usage guidance. There is no indication of when to prefer this over create_note_relationship, delete_note_relationship, or other note-relationship tools, and no stated prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It discloses a genuinely non-obvious behavioral quirk: addItems/removeItems on 'teams' is emulated client-side via read-merge-set due to a PB API bug, plus the mutual-exclusivity constraint. It still omits permission requirements, reversibility, and error/partial-failure behavior 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?

Three front-loaded sentences, each carrying distinct information: purpose, mode selection, and a behavioral caveat. No filler or restatement of the name.

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

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

For a mutation tool with no annotations and no output schema, the description covers mode selection and a key quirk but leaves out permission/auth requirements, what a successful update returns, and how failures or conflicts are surfaced. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents id, patch ops, and fields. The description reinforces the fields/patch distinction and adds the teams workaround note, but the mutual-exclusivity it mentions is already stated in the schema's own field descriptions, so added value is marginal over 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?

States a clear verb+resource: 'Update an existing Productboard entity.' This distinguishes it from create_entity/delete_entity/get_entity siblings, though it doesn't explicitly name them. The scope of the update is well defined via the two modes.

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

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

Clearly tells the agent when to use 'fields' (simple replacement) vs 'patch' (granular ops) and flags them as mutually exclusive. No exclusions around when not to use this tool versus sibling mutations, but the mode-selection guidance is explicit.

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 behavioral burden. It says 'update' but discloses nothing about permissions required, reversibility, atomicity of patch operations, partial-failure behavior, or the response shape. For an un-annotated mutation tool with nested objects, this is a substantial 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?

Two sentences, zero waste, with the core action front-loaded and the parameter guidance following immediately. Every clause 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?

A mutation tool with no annotations, no output schema, and nested objects needs more disclosure than this. The description explains the two write modes but omits permission requirements, error/partial-update behavior, and response format, leaving the agent under-informed about execution consequences.

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

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

Schema coverage is 100%, so the schema already documents id, patch, and fields, including the op enum and mutual exclusivity. The description's mention of set/clear/addItems/removeItems merely restates the schema enum, though it does add a light semantic contrast between the two modes. Baseline 3 applies.

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

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

The description states a specific verb+resource: 'Update an existing Productboard note.' This is clear and distinct from get_note/create_note/delete_note. It stops short of explicitly differentiating itself from the similarly-named update_entity sibling, which the name alone leaves ambiguous.

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

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

It provides a within-tool rule ('fields' for simple replacement vs 'patch' for granular operations), which is helpful, but gives no guidance on when to choose update_note over update_entity or other siblings, and no prerequisites or exclusions. Usage is implied rather than stated.

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