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

With no annotations, the description carries the full burden and it delivers the single most important behavior: the pb_ API key is returned once with no retrieval path, plus the owner/tier authorization constraint. It stops short of stating whether the seat is revocable or whether the key can be rotated, which would matter for this 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?

Two tightly packed sentences with zero filler. The action and its authorization gate come first, and the irreversible secret-return warning is front-loaded where it cannot be missed.

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 small mutating tool with no annotations and no output schema, the description covers action, authorization, and the critical one-time secret return. The remaining gap is the undocumented `projectId` and what happens on repeat calls for the same project.

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 only 50%: `name` is documented in the schema, but `projectId` has no description anywhere. The phrase "on a project" hints at project scoping but never clarifies how projectId is supplied or whether omitting the optional-looking parameter falls back to a default context.

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 ("Mint an agent seat on a project") with a clear scope qualifier. No sibling tool competes with this action (invite_contributor, list_members, revoke_member all concern humans/contributors, not agent seats), so an agent can uniquely identify 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?

Gives real preconditions for use — "owner only, Team tier" — which tells the agent when the call will be permitted. It does not name alternatives or explicitly say when not to use it, but no sibling is a plausible substitute, so the omission is minor.

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 that nothing is deleted, that the operation is reversible, that visibility changes in list_projects, and that ownership is required. It omits permission/error behavior for non-owned or nonexistent projects, keeping it from 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 tight sentences with the primary action front-loaded and the boolean semantics immediately parenthesized. Every clause earns its place; no 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 2-param mutation with no annotations or output schema, the description covers the essential effect, reversibility, and ownership. Missing edge-case behavior (invalid projectId, non-owned projects) is minor given the tool's simplicity.

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

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

Schema coverage is 0%, so the description must compensate. It fully explains the required 'archived' boolean (true=archive, false=unarchive), but adds nothing about 'projectId' beyond its self-evident name, leaving one of two parameters undocumented.

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 (archive/unarchive) and resource (project), and clarifies the boolean's two directions inline. It also positions itself against siblings by naming list_projects (whose output it affects) and delete (its destructive counterpart).

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?

Explains the effect of using it — hidden from list_projects — and frames it as the reversible alternative to delete, which is a usable selection cue. It states the ownership prerequisite ('a project you own') but stops short of explicit when-not conditions or naming the exact delete sibling to prefer.

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 disclose meaningful behavior: ownership ('a project you own'), a non-obvious side effect (auto-seeding the 'Later' phase), and id defaulting to a slug of the name. It omits permission/auth requirements and what happens on an id collision, which is a notable gap given the slug default.

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 compact sentences, front-loaded with the core action and side effect, then the id default. No filler, every clause adds 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?

No output schema exists, so return values need not be described. For a 2-parameter creation tool with no annotations, the description covers the key non-obvious behavior (phase seeding, id defaulting) but leaves collision handling and permissions 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 50% — only `id` is documented in the schema while `name` is bare. The description compensates for part of that gap by explaining that `id` defaults to a slug of `name`, linking the two parameters in a way the schema does not.

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 project') plus its non-obvious side effect ('seed its system "Later" phase'), and the default id derivation. Easily distinguished from siblings like list_projects, rename_project, and archive_project.

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 only implied through the rationale 'so nodes can be added immediately' — the agent can infer this precedes node creation, but there is no explicit when-to-use statement, no prerequisites, and no exclusion against other project paths.

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 well: it discloses that the link is PUBLIC, read-only, that it never expires by default unless expiresInDays is given, and that the returned token is sensitive. It omits auth/permission requirements and error behavior, keeping it from 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 tight sentences, front-loaded with the core action, then parameter behavior, then the security caveat. Every sentence adds information and none is wasted.

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 no annotations, no output schema, and 0% schema coverage, the description covers the essential behavior: security scope, TTL default, and the returned-token warning. It stops short of explaining the projectId requirement and any auth constraints, leaving minor 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 coverage is 0%, so the description must compensate, and it does: expiresInDays is explained as a TTL with the default-when-omitted behavior, settings is described as a scope with a concrete example ({ includedGoalIds: [...] }) clarifying the free-form object. projectId is only implied by 'project view' rather than named.

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 ('Mint') and resource ('PUBLIC read-only link to the project view'), clearly separating it from list_share_links and revoke_share_link. The 'PUBLIC read-only' qualifier makes the created artifact unambiguous. It does not explicitly contrast with siblings, so it falls short of the 5 bar.

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

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

Usage is implied by the action (you mint a link when you want to share a project view), and there are conditional hints about expiresInDays and settings. However, there is no explicit when-to-use/when-not guidance and no named alternative for cases like revoking or listing existing links.

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 enumerates the exact default event set and warns that the signing secret is returned only once, an operational constraint found nowhere in the schema. It stops short of covering auth/permission requirements or error behavior for non-routable URLs.

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, zero filler, with the action and the one-time-secret warning front-loaded rather than buried.

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 3-parameter tool with no annotations and no output schema, the description supplies the two facts an agent most needs: the default event set and the one-shot secret. The remaining gap is projectId semantics and permission requirements, which are undocumented in both schema and description.

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 only 33% — url is documented in-schema, while events and projectId are bare. The description compensates for events by giving its default value and item vocabulary, but says nothing about projectId, so an agent cannot tell whether it scopes the webhook to one project.

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?

"Register an outbound webhook" states a specific verb and resource, and the add/update/delete/list webhook siblings are clearly distinguishable from it without opening any 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?

Usage is implied by the outbound-notification framing, and the events default is spelled out, but the description never says when to choose this over update_webhook/list_webhooks or what prerequisite state must exist before registering.

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 it does disclose the highest-value trait: the operation is irreversible and the secret cannot be recovered, since re-registering mints a new one. However, it says nothing about required permissions/scope, what happens to queued deliveries, or the effect of omitting projectId.

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, with the destructive warning front-loaded right after the purpose. Every clause earns its place by conveying an unusable-otherwise fact.

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?

Without annotations or an output schema, the description must stand alone. It covers the critical destructive consequence but leaves open permissions, parameter roles, and error behavior — enough to call it safely only in the common case.

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% and the description adds no meaning for either parameter. It never identifies what 'id' refers to (webhook vs project) or what 'projectId' does or whether it is required in addition to id — a real gap given the two are both strings.

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 ('webhook registration'), which the sibling names create_webhook/update_webhook/list_webhooks make unambiguous. An agent can pick this out as the deletion counterpart without opening a 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?

Usage is implied by the verb and the sibling set, but there is no explicit when/when-not guidance, no mention of prerequisites, and no alternative named (e.g. disabling vs deleting). The agent must infer the 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the output shape (markdown with frontmatter, one file per node), which is real value, but never states whether the operation is read-only, whether it produces side effects or writes anywhere, or how the bundle is delivered (download, path, etc.).

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 led by the verb, with the artifact description in the middle and the usage/contrast clause last. No filler, 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?

No annotations, no output schema, and an undocumented parameter, so the description is the only source of truth. It explains the file format well but omits how the export is returned to the caller and what projectId selects, leaving gaps an agent would need filled before invoking.

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 one parameter, projectId, with 0% schema description coverage, and the description never explains it — 'the whole plan' leaves it unclear that projectId scopes which plan is exported. The description adds output-format meaning but does not compensate for the undocumented 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?

States a specific verb (Serialize), resource (the whole plan) and artifact (portable OKF file bundle, markdown with frontmatter, one file per node). The closing contrast 'rather than as JSON' implicitly separates it from the JSON-returning siblings like get_tree, but no sibling is named, so differentiation is inferred rather than explicit.

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?

'Use when you want the plan as files — for a repo, a diff, or handing it to a tool that reads markdown — rather than as JSON' gives a clear selection condition and a contrasting alternative format. It stops short of naming the concrete sibling tool an agent should call instead when JSON is wanted, so it is strong but not fully 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 behavioral burden and does so well: newest-first ordering, per-event attribution (app vs named agent), and an explicit pagination contract ('before=<_meta.next_before>, never an offset'). It omits auth/permission requirements and default page size, so not quite maximal.

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: identity and ordering first, then the deleted-node rationale, then filters, then pagination, then the undo path. Every clause adds operational detail rather than 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?

Rich enough for an 8-param read tool with no output schema and no annotations, covering return ordering, filtering, pagination, and a cross-tool workflow. The main holes are the undocumented limit and projectId parameters and the absence of any authorization note.

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, and it documents 6 of 8 params including enum-like values absent from the schema (action add|update|delete|restore, source app|api_key, ISO format for since/before). It leaves limit and projectId entirely undocumented, a real but modest gap.

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 (Read) and resource (the plan's history) and enumerates the event types (add/update/delete/restore) plus attribution. It further distinguishes itself from sibling list_nodes by explaining changelog is the way to find a node after deletion, which /nodes cannot do.

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 when to use this over /nodes ('find a node AFTER it was deleted') and routes to the follow-up tool ('undo with mutate {action:restore, nodeId}'). It even specifies ordering within the restore (parent before children), leaving little 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?

With no annotations, the description carries the full burden and partially meets it: it discloses the default relation composition (ancestors+siblings+children), the accepted alias names (up/down/lateral/context), and the trap that 'children' returns a full subtree. It says nothing about permissions, pagination, or return 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?

Three tight sentences, front-loaded with the core action and the relation enumeration. The closing sentence about the missing children-only view is dense but earns its place as a behavioral warning.

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 key ambiguity (what each relation returns) is resolved, which is the most valuable thing for this tool. But with no output schema, no annotations, and two undocumented parameters, the description is only adequate, not 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 0%, so the description must compensate for all three parameters. It documents relation thoroughly (values, aliases, default) but leaves nodeId and projectId entirely unexplained, so coverage is only partial.

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 ('Get a node') and immediately clarifies what 'tree' means by enumerating the relation modes. It implicitly separates itself from list_nodes/search by framing the tool as fetching one node with surrounding context, though it never names a sibling 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?

It gives the default relation (context) and warns that there is no children-only view, which steers the agent toward subtree. However, it never says when to reach for this tool versus list_nodes, search, or read_view, so selection guidance is only implied.

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 that a passwordless Clerk invite is sent and that one seat is consumed regardless of project count, plus the owner-only and Team-tier requirements. However, it omits duplicate-invite handling, invite expiration, whether the invite can be revoked, and other side effects.

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 tightly written sentences with zero waste. The core action and the most important constraints are front-loaded, 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 two-parameter mutation tool with no output schema and no annotations, the description covers the critical prerequisites (owner only, Team tier) and the notable seat behavior. It is nearly complete, missing only edge-case behavior such as what happens when the email is already associated with a member.

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%. The projectIds parameter is already documented in the schema, and the description repeats 'projects you own' without adding format or validation detail. The email parameter has no schema description, and the description adds only that an invite is sent 'by email', which is minimal.

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 (invite), resource (guest contributor), channel (by email), and scope (one or more projects you own). It clearly distinguishes a guest contributor invite from generic member or agent seat operations, though it does not name an alternative sibling tool 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?

It supplies clear contextual constraints: owner only and Team tier. This tells an agent when the tool is applicable, but it does not state when-not to use it or route to alternative tools like add_agent_seat for non-guest seats.

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 implies a read-only listing via the verb "List," but says nothing about permissions, pagination, result size, or ordering, and no output schema exists to fill that gap. Only the filter semantics are disclosed.

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, front-loaded sentences with no filler; the purpose comes first and the parameter hints follow. Slightly cryptic phrasing ("phases/iterations" without clarification) keeps it from a 5.

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 3-parameter tool with zero schema descriptions, no annotations and no output schema, the description is too thin. It never explains projectId, the full status value domain, or what a returned iteration looks like, leaving real gaps an agent must guess around.

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

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

Schema coverage is 0%, so the description must compensate, and it partially does: it explains the effect of current:true and status:active in terms the bare schema cannot. However, projectId is left completely undocumented, and status is shown with only one example value rather than its full set of accepted values.

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 ("List phases/iterations"), so an agent immediately knows this is a read/lookup tool for iteration objects. It does not, however, differentiate itself from sibling listers such as list_projects or list_nodes, which is why it falls 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?

There is no statement of when to use this tool versus alternatives, nor any preconditions or exclusions. The filter hints (current/status) describe parameters, not when-call guidance, so an agent gets no routing help.

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 usefully discloses the authorization requirement ('Any member can read this'), but says nothing about pagination, result format, ordering, or behavior when the project has no 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 resource and scope front-loaded and zero filler. Every clause adds information.

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

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

For a simple read-only list tool with one parameter and no output schema, the description covers what is returned at a high level (member and agent seats plus owner). It is nearly sufficient, with only the parameter format and result shape left implicit.

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 one parameter (projectId) with 0% schema description coverage, so the schema explains nothing. The description implies project scoping ('on a project') but does not name the parameter, its format, or whether it is required, leaving a real gap.

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 (list) and resource (members), and clarifies scope by naming 'human and agent seats' plus 'the owner'. This is clear enough to separate it from siblings like revoke_member or invite_contributor, though it never explicitly names an alternative.

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 line 'Any member can read this' gives a permission precondition, which is real usage context, but there is no explicit when-to-use guidance or pointer to sibling tools such as list_projects or revoke_member. Usage is only implied.

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. '(bulk read)' implies a read-only, batch operation, but there is no mention of permissions, pagination, result limits, or whether the project scope is required — significant gaps for a bulk enumeration 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?

Two terse sentences with the resource and mode front-loaded and no filler. Well-sized for the amount of information conveyed, though it is brief at the cost of completeness.

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 bulk-read tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin. It omits pagination/limit behavior, whether projectId is required, and any return-shape hint, leaving the agent under-equipped to call it correctly.

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

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

Schema coverage is 0% with three undocumented params, so the description must compensate. It helpfully enumerates the type values (goal|need|approach|job|task) that the schema leaves as a bare string, and names the iteration filter, but projectId is only implied by 'in a project' and no formats are given.

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 nodes in a project') and adds a mode qualifier ('bulk read'). It does not, however, distinguish itself from siblings like get_tree or search, which also enumerate content.

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 when-to-use or when-not-to-use guidance and no alternatives named. The '(bulk read)' hint implies a contrast with single-item reads, but the agent is left to infer when this beats get_tree or search.

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 behavioral burden. It does disclose a non-obvious default (archived projects are hidden), which is genuine value beyond the schema, but it says nothing about auth requirements, pagination, or result shape 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?

Two tight sentences, zero waste, with the scope statement front-loaded and the parameter behavior following. 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 simple read-only list tool with one optional param and no output schema, the description covers scope and default filtering behavior adequately. Minor gaps around result ordering and pagination are not essential 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?

With 0% schema description coverage on a single boolean parameter, the description fully compensates by explaining that includeArchived controls whether archived projects appear. The parameter's meaning is clear without opening 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 and resource ('List the projects') plus a clear ownership/membership scope that separates it from list_members and list_nodes. It does not name a sibling explicitly, but the scope qualifier makes the 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?

The description implies when the tool applies (fetching your projects) and clarifies the archived-visibility condition, but offers no explicit when-to-use vs alternatives guidance and no 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 disclosure burden. It helpfully enumerates the return fields (createdAt/expiresAt/revokedAt and an active flag), which tells the agent revoked and expired links are still listed and discriminating via the active flag. It does not cover auth requirements, pagination, ordering, or whether results are scoped when projectId is omitted.

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 core action and the field list, with the 'audit half' framing as a compact second sentence. No filler; only the missing operand (required vs optional) keeps it from being fully tight.

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

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

For a one-parameter, read-only list tool with no output schema and no annotations, the description supplies the key return-shape detail but omits requiredness of projectId, pagination behavior, and any auth preconditions. Adequate but not fully sufficient given the zero annotation and zero schema-description coverage.

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

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

Schema coverage is 0% and the schema marks projectId as optional, so the description is the only source of meaning. 'for a project' conveys that projectId scopes the listing, but it does not clarify whether the parameter is required or what a project-less call returns, leaving ambiguity the agent must guess at.

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 share tokens (share links) minted for a project. It also names the returned fields and frames itself as the read/audit counterpart to create_share_link and revoke_share_link, so an agent can place it in the share-link trio without opening a 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?

The phrase 'The audit half of the share loop' implies this is the inspection/audit step rather than the minting or revoking step, which is useful orientation. However, it never explicitly states when to call this versus create_share_link or revoke_share_link, nor any prerequisites such as needing a projectId.

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 that secrets are never returned and that lastStatus/lastDeliveryAt are included. However, it omits permission requirements, pagination/ordering behavior, and whether the list can be empty, which are the traits an agent would still need.

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 no filler; the scope statement is front-loaded and the parenthetical adds a genuine constraint rather than restating 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 simple one-parameter read tool with no output schema, the description covers scope, safety (no secrets), and the key return fields. Missing only secondary details like pagination or required permissions, so it is close to complete for this complexity level.

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 one parameter (projectId) at 0% schema description coverage. 'On a project' implicitly ties the call to a project identifier, but the description adds no format, required/optional status, or default information beyond that implication.

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 (list) and resource (outbound webhooks) scoped to a project, which cleanly separates it from the mutating siblings create_webhook, update_webhook, and delete_webhook. The parenthetical about secrets clarifies the read-only nature of the 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?

The phrase 'so you can spot a failing receiver' implies a diagnostic use case and the tool is obviously the read-only counterpart to the webhook mutation siblings, but it never explicitly says when to prefer it or when not to use it. Usage must be inferred.

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 does disclose one genuinely useful behavior beyond the schema: passing a UUID idempotencyKey makes retries safe because a replay returns the original result instead of double-creating. However, for a delete-capable mutation tool it says nothing about permission requirements, reversibility of deletes, or batch atomicity.

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 that are front-loaded with the core purpose before drilling into action values, payload shape, and idempotency. The eight-value action enumeration is long but earns its place since the schema omits the enum.

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 4-parameter, nested-object mutation tool with no annotations and no output schema, the description covers action semantics, payload shape, and idempotency, but leaves projectId undefined, gives no sense of what a successful response contains, and omits permission and reversibility context that an agent needs before issuing deletes.

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 only 25% and the schema types 'action' as a bare string with no enum, so the description's enumeration of the eight legal action values is essential compensation. It also clarifies that payload carries the remainder of the mutate body with concrete shapes (node | nodeId+data | mutations | iteration) and that idempotencyKey is a UUID. projectId is left unexplained, keeping it from a 5.

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 concrete verb+resource: create/update/delete plan nodes and phases, and enumerates the eight supported action values, which is far more specific than the bare name 'mutate'. It does not explicitly distinguish itself from read-side siblings like list_nodes or get_tree, 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 action list implies the usage modes (add/update/delete/batch/iterations/classify) and the idempotency hint implies retry scenarios, but there is no explicit when-to-use versus alternatives, no exclusions, and no prerequisite guidance (e.g., which sibling to call to obtain nodeId before mutating).

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 burden; it does convey that this is a read of ephemeral current state and names the returned fields, which is useful signal. It says nothing about permissions, project scoping, or what happens when no view exists, leaving behavioral gaps.

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

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

A single sentence, front-loaded with the verb and the key concept ('what the user is looking at now') before listing fields. Efficient, though the trailing field enumeration could arguably be pushed to an output schema.

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 with no annotations and no output schema, the inline field list partially substitutes for a return spec. However, nothing is said about the projectId parameter or the scope/format of the response, so it is only minimally 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 0% and the sole parameter projectId has no description in either schema or prose. The description adds no meaning about what projectId selects or whether it is optional, so it fails to compensate for the coverage gap.

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?

Uses a specific verb ('Read') plus a clearly scoped resource ('what the user is looking at now'), and enumerates the view fields returned (view_mode, selected_iteration, expanded_nodes, etc.). This makes it distinguishable from non-view siblings like get_tree or list_nodes, though it never names the mutating counterpart set_view 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 phrase 'now' implies reading current UI state, but there is no statement of when to prefer this over set_view, get_tree, or list_nodes, and no exclusions or prerequisites given. Usage must be inferred from the 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?

With no annotations, the description carries the full burden. It usefully discloses that the operation is owner-restricted and that the id is immutable ("keep using the same projectId afterwards"), which is real behavioral value, but says nothing about reversibility, what the response returns, or failure modes 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?

Two tight sentences with zero filler; the core action and the key post-condition (immutable id) are both 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?

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description covers the essential permission and id-stability facts but leaves return behavior and error/reversal semantics unspecified.

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

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

Schema coverage is 0% with two params, so the description must compensate. It clarifies that `name` is a display name and implies `projectId` identifies the target and is unchanged, but it doesn't state that `projectId` is required/optional or give format expectations. Partial compensation only.

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 ("Change a project's display name") and narrows scope by distinguishing the display name from the immutable id, so an agent won't confuse it with archive_project or create_project.

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 "(owner only)" parenthetical gives a clear authorization precondition for when this tool is usable. It does not name alternatives or when-not conditions, but the usage context is unambiguous for a rename operation.

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 and it does disclose a real side effect: removing an agent seat revokes its API key once the last membership is gone. However, it omits whether the operation is reversible, what permissions are required, whether it is idempotent, and what happens to other memberships or resources owned by the removed member.

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 no filler, and the core action is front-loaded ahead of the secondary API-key consequence. The parenthetical '(human or agent)' is efficient disambiguation rather than 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 destructive mutation tool with no annotations, no output schema, and zero schema description coverage, the description is too thin. It should at minimum state permission requirements, idempotency/reversibility, and the meaning of the optional projectId; the API-key note is a good start but not enough.

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, and it does not. It never explains userId (required) versus projectId (optional), nor what omitting projectId means—whether it defaults to a current/default project or is invalid. With two undocumented parameters, the description leaves the caller guessing.

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 ('Remove') plus resource and scope ('a member (human or agent) from a project'), which clearly separates it from list_members, add_agent_seat, and invite_contributor. It also clarifies the entity type covered (human or agent), which is useful. It stops short of explicitly contrasting itself with near-neighbors like revoke_share_link, so it lands at 4 rather than 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?

There is no statement of when to use this tool versus alternatives (e.g., vs. removing a seat, vs. invite/contributor flows) and no prerequisites such as required admin role. The only usage-adjacent content is a consequence note about agent seat API keys, which is behavioral rather than routing guidance.

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 and does meaningfully well: it discloses eventual-consistency timing (public link stops serving within ~30s due to edge cache) while the backing record dies immediately. It omits irreversibility/idempotency and authentication requirements, but the cache-vs-record distinction is real behavioral value.

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, then the observable effect. Every clause earns its place with no 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 mutation tool with no annotations and no output schema, the description covers the runtime effect well but leaves the optional projectId undocumented, gives no error/failure behavior for an invalid or already-revoked token, and states no prerequisites. Just enough to call it, not enough to call it confidently.

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% for two parameters, so the description must compensate and largely does not. 'Token' is only loosely named as a share token with no format hint, and the optional projectId parameter is never mentioned anywhere.

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 ('Revoke a share token') that is unambiguously distinct from the sibling create_share_link and list_share_links. An agent can identify the operation 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?

Usage is implied by the verb — you call this on a token you previously created — but there is no explicit when-to-use, no precondition (e.g. must own the link), and no guidance on how it relates to siblings like delete_webhook or revoke_member. Adequate but with a clear gap.

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 does disclose the return shape usefully ('next prompt + opaque state, or a terminal changeset with a focus hint'), which is real behavioral value, but it omits side effects, permission requirements, and whether state is persisted across calls.

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 tight sentences with no filler, front-loaded with the purpose and immediately followed by the return contract and the body instruction. Dense and efficient, though the parenthetical flow list slightly interrupts the flow of reading.

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 stateful, nested-object tool with no output schema and no annotations, the description does cover the return contract and flow values, which is the critical part. However, it leaves projectId undefined and gives no guidance on how state/response should be threaded across successive calls, which is central to a multi-step workflow.

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%; the nested body object is documented only as '{ flow, state?, response? }' with no enums in the schema. The description compensates by supplying the flow values and telling the agent to place the 'v1 workflow body in body', but projectId is left unexplained in both the schema and the 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?

States a specific verb (run) and resource (Story-Mapping methodology workflow), and enumerates the flow values (add | task-curate | phase-assign), which distinguishes it from every sibling (webhook/share/member/project utilities). It falls short of 5 because 'Story-Mapping methodology workflow' is a domain concept the agent must already know; no sibling is named as a contrast.

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 or when-not-to-use guidance, and no alternative tool is referenced. The flow enum hints at three sub-modes but never explains which flow to pick or under what circumstances.

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 the return shape (nodes ranked by similarity, with ancestor paths), which is real added value, but says nothing about result limits, pagination, or whether projectId scoping affects ranking.

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, zero filler, with the capability statement front-loaded and the routing instruction second. 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 two-parameter read tool with no annotations or output schema, the description covers capability and return shape adequately but leaves the projectId scoping parameter and any result-size behavior unexplained.

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 only 50%. The description implies a natural-language query via 'semantic search,' matching the documented q parameter, but adds no format or length guidance and is silent on projectId, which is undocumented in both the schema and the 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?

States a specific verb and resource ('Semantic search over the ProductBrain plan') and immediately distinguishes itself from the graph-walking siblings by warning against scanning nodes by label. An agent can tell this apart from list_nodes or get_tree without opening any 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?

Explicitly prescribes priority ('Use this FIRST for any lookup') and an exclusion ('never scan all nodes by label'), which routes the agent away from list_nodes. It stops short of naming the alternative tool directly, so it is clear context rather than a fully specified when/when-not rule.

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 says 'Drive the live canvas' but never discloses whether changes are persistent, whether they affect other collaborators, whether auth/project scoping applies, or whether any node state is destroyed (collapse/expand could hide content). For a mutation tool with zero annotation coverage this is a real 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 short sentences with the core purpose front-loaded before the command enumeration. Nothing is wasted, though the second sentence is dense shorthand ('...') rather than cleanly structured.

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 nested free-form command object, 0% schema description coverage, no annotations, and no output schema, the description is under-specified. It gives the command-type list but nothing about per-command parameters, projectId semantics, or effects, which an agent needs to invoke six distinct operations correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does partially: it spells out the discriminator values for the nested 'command' object (setViewMode|selectIteration|zoomToNode|expandNode|collapseNode|focusGoals) plus an ellipsis hinting at per-command fields. However it does not explain what each command type does or what projectId selects, leaving the per-command arguments undocumented.

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 concrete action ('Drive the live canvas') and enumerates the actual command types (setViewMode, selectIteration, zoomToNode, expandNode, collapseNode, focusGoals), so the agent knows this manipulates live view state rather than reading it. It stops short of naming read_view or another sibling to sharpen the boundary, 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 guidance, no when-not-to-use, and no mention of the obvious alternative read_view (which presumably reads what this tool mutates). The command list implies usage but the agent must infer everything about context and 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 and does so well: it discloses storage semantics ('Stored for the team to read'), the absence of a reply channel, a concrete rate limit (max 20 per 24h), and a data-sensitivity constraint (no credentials, customer records, confidential plan content). These are exactly the traits an agent needs and that structured fields do not supply.

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 purpose, then layered constraints (storage, no reply, confidentiality, rate limit) in tight clauses. Every sentence earns its place and there is no 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?

No output schema and no annotations, so the description must stand alone; it covers behavior thoroughly for a low-complexity submission tool. The remaining gap is guidance on the undocumented 'projectId' parameter and the nested 'context' object, which leaves the definition slightly short of 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 60%. The description adds real meaning to 'summary' (self-explanatory, since there is no reply channel) and enumerates the 'kind' values, but it never mentions 'projectId' or explains 'context'/'details', so it only partially compensates for the uncovered parameters. Baseline 3 fits.

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 ('Tell the ProductBrain team how PB should improve') and enumerates the concrete feedback categories (feature, friction, bug, note). No sibling tool overlaps, so differentiation is inherent, and an agent can tell exactly what this 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?

Gives clear context for when to use it via the category enumeration and an implicit exclusion ('not added to any plan'), plus a batching hint tied to the rate limit. It does not name an alternative, but no sibling tool offers a comparable path, so the gap is minor.

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 behavioral burden, and it does real work: it declares this is a read, that the scope is the caller's own account ('your own'), and it surfaces the 402 failure mode that motivates the call. It does not mention cost, caching, or refresh cadence of the balance figures, which keeps it out of 5 territory.

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, no filler. The first front-loads the returned data, the second delivers the trigger and the consequence. 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 and no annotations, the description must convey return content, and it enumerates the categories of data returned as well as the failure mode the caller should preempt. Minor gap: no indication of units, formatting, or how often the balance updates, which an agent cannot recover from structured fields here.

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 takes zero parameters, so the baseline of 4 applies. The description correctly implies a self-scoped, argument-free call ('your own tier'), which is consistent with the empty schema and clarifies that no account identifier is 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?

States a specific verb ('Read') and enumerates exactly what resource set is returned: tier, API access, AI-credit balance, seat/project/node limits, billing period. No sibling in the list (webhooks, share links, members, projects, iterations) overlaps with this function, so an agent can select it unambiguously.

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 trigger condition with rationale: check before a large run to self-throttle and avoid a 402 mid-flight. That is strong, actionable context. It stops short of a 5 only because there is no explicit 'when not' framing and no alternative to name for the pre-flight check.

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 that the secret is preserved unless rotateSecret is passed, that a rotated secret is 'returned once' (one-time visibility, not re-retrievable), and that delete+recreate has a receiver-breaking side effect. It omits auth/permission requirements and whether url/events replace or merge with existing values.

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-loaded with the core operation and followed immediately by the secret behavior and the alternative routing advice. No 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 5-parameter mutation tool with no annotations and no output schema, the description covers the most dangerous behaviors (secret rotation, one-time return) but leaves projectId undocumented and unclear whether omitted fields are preserved or cleared. Adequate but with visible 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 explain parameters itself. It adds real meaning for url, events, and rotateSecret, and id is implied by 'same id', but projectId is never mentioned and no parameter's format or merge semantics are clarified.

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 ('Reconfigure'), the resource ('webhook'), and the scope ('in place (same id)'), which cleanly separates it from create_webhook and delete_webhook in the sibling list. An agent can identify the operation without reading 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?

Explicitly states the preference: 'Prefer this over delete+recreate, which breaks the receiver,' giving a when-to-use and a named alternative pattern with a reason. It does not cover when this tool is inappropriate (e.g., non-existent or archived webhooks), so it stops just short of full routing guidance.

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