DB Planner

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

Description discloses behavioral details beyond annotations: image stored as a blob, card placed at x,y, sizing capped at 640 units, base64 formats accepted, and EITHER/OR between data and sourceUrl. Annotations only cover openWorldHint and destructiveHint, so this is genuinely additive.

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, each earning its place: purpose/return, parameter semantics, and post-processing behavior. No filler or repetition of 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 single-required-param tool with an output schema and rich annotations, the description covers usage, edge-size behavior, storage semantics, alternatives, and follow-up operations. Nothing essential is missing for an agent 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?

While schema covers parameter names and types at 100%, the description adds meaning not present in the schema: mutually-exclusive data/sourceUrl, base64-encoding, supported formats, https requirement, server-download behavior, and 640-unit cap. This materially improves an agent's invocation correctness.

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: 'Put a picture on a project's board' and returns its image id. Clearly distinct from siblings like update_board (modify), get_board_image (retrieve), and draw_arrow (vector drawings).

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 when to use the tool (when adding an image) and explicitly routes follow-up resizing/moving to update_board's images map. It could more explicitly exclude update_board for adding, but the 'afterwards' guidance is clear.

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

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

Annotations already mark this read-only, so the bar is lower. The description adds useful behavior: it searches only published listings, returns counts and a category breakdown, and exposes the full category vocabulary. This goes beyond the raw schema and gives the agent a clear model of what the call will yield.

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 fluff. The first explains scope and return contents; the second gives the intended use. All content 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 description is complete enough for a 6-parameter, read-only search tool with a rich output schema. It covers what is searched, what is returned, and why an agent would call it. Minor omissions like pagination details are already handled by the schema and annotations.

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 input schema already documents every parameter. The description doesn't add much parameter-level meaning, though it does usefully note that the category vocabulary returned is the exact set accepted by the category filter and publish_listing.

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 ('Search') and identifies the exact resource ('the public template marketplace'). It clearly differentiates from siblings like get_template, list_my_listings, and publish_listing by emphasizing 'published listings only' and the category-vocabulary return.

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 a concrete use case: 'Use it to find a schema to start from before writing DBML by hand.' This helps an agent know when to call it, though it doesn't explicitly state when not to use it or name alternatives such as get_template for a single listing.

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?

Annotations provide only readOnlyHint=false and destructiveHint=false, which is consistent but not informative. The description adds no behavioral details such as side effects, permission requirements, duplicate-name behavior, or what happens on the board. For a creation tool, this leaves important operational behavior undisclosed.

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 concise sentences with the action front-loaded. The second sentence provides relevant context about what a project contains, which helps an agent understand the domain without adding fluff.

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 full parameter schema, output schema, and project-context sentence give enough information for a straightforward create call. It could be more thorough about edge cases or permissions, but for this tool's complexity the description is adequately 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?

All five parameters are already documented in the schema with 100%% coverage, including kind values and naming conventions. The description does not need to re-explain parameters, and adds only contextual information about project content rather than parameter-level semantics.

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

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

The description clearly states the action ('Create') and the resource ('a document in a project'), and adds useful context that projects contain database schemas and diagrams. It does not explicitly contrast with siblings like update_document or create_project, but the verb and object make the tool's role 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 to use the tool: to add a schema or diagram document to a project. However, it does not provide explicit guidance about when to choose this over update_document, use_template, or other sibling tools. The usage is clear enough from context but not fully 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?

With annotations providing destructiveHint=false and openWorldHint=false, the description adds useful behavioral context: creating the org also seeds a first project and returns both identifiers. It clearly communicates the primary side effect beyond the minimal annotation safety profile.

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

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

The description is a single, focused sentence that states the action, the side effect, and the return value. Every part is useful, and the core behavior is front-loaded.

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

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

Given the small parameter surface, full schema coverage, and presence of an output schema, the description sufficiently covers what the agent needs: the action, the seeded project behavior, and the return shape. No material gap remains.

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%, with each parameter already described in the input schema. The description adds slight context by tying firstProjectName to the seeded project and the return value, but does not significantly extend the parameter meaning.

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 ('Create') and resource ('team organization'), and clearly states the seeded first project as part of the action. It distinguishes itself from siblings like create_project by indicating this tool creates an organization plus its initial project, not just any 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 description implies usage for creating an organization with an initial project and names the seeded project, but it does not explicitly contrast with create_project or other org/project tools. The context hints at the right time to use it, but the guidance is not 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?

The description adds an authorization requirement ('org staff only') that is not present in the annotations, which is valuable behavioral context. It also aligns with destructiveHint=false since creating a new project is not destructive. It does not discuss idempotency or duplicate handling, but for a simple create tool the disclosed auth boundary is the key behavioral trait.

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

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

The description is a single, front-loaded sentence with no filler words. It states the action, the resource, the scope, and the access condition in eight words, earning its place entirely.

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 create tool with full schema coverage and an output schema, the description covers the essential behavioral context: what is being created, where it is created, and who is allowed to create it. No critical invocation details are 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?

The input schema has 100% description coverage for all three parameters, including defaults and formats, so the description does not need to repeat parameter details. The description adds no parameter-specific meaning beyond the schema, matching the baseline for fully documented schemas.

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 ('Create'), a clear resource ('a project'), and a containing scope ('in an organization'). It also includes an access restriction ('org staff only'), which keeps it distinguishable from sibling tools like create_org and create_document.

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 indicates when to use it: to create a project within an organization, and who may do so via 'org staff only.' It does not explicitly name alternatives, but the operation is unambiguous and the access exclusion gives practical usage 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?

The destructive nature is already conveyed by the `destructiveHint: true` annotation, so the description does not need to repeat it. The phrase 'from a project' adds scoping context not present in annotations. However, no additional behavioral details such as permanence, cascading effects, or authorization requirements 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?

The description is one concise sentence that adds the project scoping beyond the title. There is no unnecessary wording or duplicated detail from the 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 two-parameter deletion tool, the description, schema, and annotations together provide enough information to invoke the tool correctly. The eisting output schema covers return values, and destructiveHint covers safety. Missing alternative routing is the only notable gap, which is already accounted for in usage guidelines.

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

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

The input schema has 100% description coverage, including UUID formats for `projectId` and `docId`. The tool description adds no parameter-specific information, but the schema already fully documents the parameters, waranting the baseline score of 3.

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

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

The description clearly identifies the operation as deleting a document, specifies the resource (document), and scopes it to a project. This distinguishes it from sibling tools like delete_org and delete_project, and from update_document.

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

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

No guidance is provided about when to use this tool instead of alternatives like update_document or create_document. The context is obvious from the verb, but there is no explicit or implicit discussion of alternatives 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?

Beyond the destructiveHint annotation, the description discloses two important behaviors: an authorization constraint ('owner only') and a cascading side effect on projects. These are exactly the details an agent needs to predict the impact of invoking this tool.

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

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

The description is two short clauses with no filler. It front-loads the action and resource, then immediately provides the most decision-relevant behavioral details.

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 a complete schema, an output schema, and destructiveHint/openWorldHint annotations, the description covers permission and cascade behavior. Nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents orgId as a UUID. The description does not add additional parameter semantics, but it does not need to because the schema carries the burden.

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 ('Delete'), a specific resource ('an organization'), and adds two key qualifiers: 'owner only' and 'Cascades to its projects.' This clearly distinguishes it from sibling delete tools like delete_project and delete_document.

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

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

The description gives clear usage context by requiring owner-only invocation and implicitly warns that the operation affects projects as well. It does not explicitly name alternative tools for deleting projects or documents, but the resource scoping makes the appropriate choice obvious.

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?

Annotations already supply destructiveHint: true, so the destructive nature is known. The description adds valuable behavioral context: deleting a project also deletes its documents and board, a non-obvious side effect an agent should know before invoking.

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 concise sentence that puts the action and the destructive scope up front. There is no filler or repetition of schema-level details.

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 tool with a UUID schema, an output schema, and destructiveHint annotation, the description is sufficient. It names the resource, the action, and the important cascade effect, leaving no material gap 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?

The input schema already describes projectId as a requiredUUID, and schema description coverage is 100%. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and resource ('project'), and explicitly states the scope ('along with its documents and board'). This clearly distinguishes it from sibling tools like delete_document and delete_org.

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

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

The description implies when to use this tool by identifying what it deletes, but it does not explicitly state when to choose it over alternatives such as delete_document or delete_org. The cascade behavior suggests whole-project deletion, but the guidance is left 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?

Beyond the sparse annotations, the description discloses meaningful behavioral details: point-count limits (1000 for ink, 2–50 for arrows), flat or object coordinate input, rounded storage to 2 decimals, single-point dots, and arrow-head placement on the last segment. This gives the agent a strong model of how the tool behaves and stores data.

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 four sentences are front-loaded with the core purpose, then organized by kind and point semantics, with no filler. Each sentence contributes constraints or behavior not available elsewhere.

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 drawing tool with two kinds and nontrivial point semantics, the description covers the operation, constraints, formats, and return value; an output schema exists to supply the exact response shape. The only minor gap is the absence of sibling comparisons, which was already accounted for in usage_guidelines.

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

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

Although the schema already documents every parameter, the description adds significant semantics: it explains the meaning of points per kind, constraints on point count, coordinate formats, rounding behavior, and the returned id. These details exceed the schema descriptions and materially reduce the chance of misuse.

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 precise action: 'Draw one line drawing on a project's board and return its id,' immediately establishing what the tool creates and returns. It clearly distinguishes the two kinds (freehand ink vs. arrow), but it never names the sibling draw_shape or explicitly says what this tool is not, 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?

The description gives clear conditions for choosing kind 'ink' versus 'arrow' and for using the tool on a project board, so the intended use is implied. However, it offers no explicit guidance about when not to use this tool or when to reach for a sibling such as draw_shape or erase_drawings.

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?

Beyond the annotations, the description discloses key behavioral details: points represent two opposite bounding-box corners in board world coordinates, text is optionally bound inside the shape, and the shape grows downward to fit long text. It is transparent without contradicting the annotations.

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 deliver the core purpose, critical point semantics, and an important exclusion for alternative content in update_board. There is no filler or redundant restating of the 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?

Given the rich input schema, output schema, and annotations, the description is complete enough for an agent to invoke the tool correctly. It explains the core geometry, optional text behavior, and where to route non-shape content.

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

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

The input schema already covers all 8 parameters, so the baseline is 3. The description adds meaningful extra context beyond the schema, such as board world coordinates for points and the downward-growth behavior for long text, pushing it above baseline.

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

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

The description states a specific verb and resource: draw one rectangle, diamond, or ellipse on a project's board and return its id. It clearly distinguishes from update_board by explicitly noting that free text without a shape, groups, and links go through the sibling tool.

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

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

The description gives concrete when-to-use context for drawing shapes and explicitly names the alternative path for non-shape content via update_board. This gives an agent enough routing information to choose the correct tool without ambiguity.

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?

Annotations already flag destructiveHint=true, and the description adds valuable scope transparency: card positions, collapsed flags, and notes are untouched. This tells the agent exactly what will and won't be affected, going beyond the annotation alone.

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 with the action front-loaded. The first sentence names the operation and resource; the second explains the two invocation modes and explicitly scopes what is untouched. No filler 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 destructive tool with an output schema and destructiveHint annotation, the description is complete: it covers target, deletion modes, and non-affected board data. The schema handles edge behavior like all being ignored when strokeIds is supplied, so nothing essential 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 projectId, all, and strokeIds are already fully documented. The description's 'stroke ids to remove, or set all to true' restates the schema semantics rather than adding new parameter-level detail.

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

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

The description opens with a specific verb and resource: 'Delete drawings from a project's board.' This clearly distinguishes it from siblings like draw_stroke, list_drawings, add_board_image, and update_board, none of which remove drawings.

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

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

It gives concrete operational guidance: pass strokeIds to remove specific drawings, or set all=true to clear the board. The deletion context is clear, though it doesn't explicitly name when-not-to-use alternatives such as draw_stroke or update_board.

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?

Annotations already declare readOnlyHint=true, so the safety profile is established. The description adds meaningful behavioral context beyond that: it reveals the full scope of board data, including full point lists for drawings, and the important limitation that rendered images omit groups and links. This goes beyond static annotations without contradicting them.

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

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

The description is two sentences with no filler. The core action is front-loaded, followed by a dense but purposeful enumeration of returned elements, and the key caveat about groups/links is placed last for emphasis. 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 an output schema present, the return structure is already defined. The description covers what makes this tool unique, what data it returns, and the critical limitation of the rendered image. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, and the single required parameter projectId is already documented as 'Project id (uuid).' The description does not add new parameter-level semantics, so the baseline score 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 uses a specific verb ('Get') with a clear resource ('a project's board') and enumerates the exact contents returned (card positions, sticky notes, drawings, images, groups, links, updatedAt). It distinguishes itself from the related get_board_image tool by stating groups and links are only visible here.

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

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

The description explicitly positions this tool as 'the only way to see groups and links' and contrasts it with the rendered board image, which does not draw them. This gives the agent a clear decision rule for when to prefer this tool over the image alternative.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description reveals important behavioral traits: the image excludes diagram cards, groups, and cross-links; it returns a PNG plus a one-line summary; format='svg' returns the vector source as text; and scale is clamped to keep the image inline-able. This prevents false negative conclusions about writes.

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 dense but efficient: it front-loads the main action and purpose, then adds the critical caveat about what is not drawn, and ends with the alternative tool. Every sentence contributes either to selection, invocation, or interpretation of the result.

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

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

Given the lack of an output schema, the description sufficiently explains the return value ('PNG plus a one-line summary') and the SVG variant. It also covers behavioral caveats and the sibling alternative, so an agent has enough context to select and invoke the tool correctly without additional ambiguity.

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

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

The input schema already documents all 7 parameters with defaults and descriptions, so the baseline is 3. The description adds meaningful context beyond the schema, such as the scale clamping behavior, that SVG format returns the source as text, and that the result is a PNG plus summary. This enriches parameter understanding without being redundant.

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 and resource: 'Render a project's board as an image and return it.' It clearly states what the image contains—tables, enums, relationships, sticky notes, drawings, pasted images—and differentiates itself from the structural board tool by warning that diagram cards, groups, and cross-links are not drawn.

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 use cases: 'Use this to SEE the board - to check a layout you just wrote, or to find cards that overlap or sit far from what they relate to.' It also gives a when-not-to-use signal by stating that an absent frame or connector is not evidence the write failed, and routes the agent to get_board for those elements.

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?

Annotations already declare readOnlyHint=true, so the description's non-mutating behavior is consistent and doesn't need restating. The description adds useful context: it returns members, plan, and billing summary, which clarifies the scope of data. It doesn't explicitly state that billing summary might be sensitive or that it returns a 404 if not found, but the annotations cover the key safety trait and the output schema likely details return 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?

One clear, front-loaded sentence with no filler. It states the action, the resource, and the included data without redundancy. Every word 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?

Given the simple single-parameter input, read-only annotations, and presence of an output schema, the description is largely complete. It names the included data (members, plan, billing summary), which gives the agent a good sense of what it will receive. It omits explicit error behavior, but for a read-only lookup with a well-schematized parameter this is a minor 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 parameter orgId is well documented as 'Organization id (uuid).' The description adds no additional semantic detail beyond the schema, such as where to find orgId or what constitutes a valid org. Baseline 3 is appropriate because the schema carries the full parameter explanation.

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 ('Get'), a specific resource ('one organization by id'), and lists the key included data ('members, plan, and billing summary'). This clearly distinguishes it from sibling tools like list_orgs (which lists organizations) and create_org/update_org (which mutate organizations).

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 states the tool gets a single org by id, implying the user must know the org ID. It distinguishes from list_orgs implicitly by focusing on one org and its details, but it does not explicitly say 'use list_orgs to find orgs' or state when not to use this tool. Context is clear, but no explicit exclusions or alternatives are named.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to restate the read-only nature. It adds a useful detail by specifying 'public' display names, but it does not explain behavior for unresolved emails or mention any limiations or failure modes.

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

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

The description is a single sentence that front-loads the verb and object, with no filler or repetition. Every word contributes to understanding the tool's purpose.

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 tool with an output schema present, the description covers the essential invocation context. It could theoretically mention behavior for unresolved emails or ordering, but those details are not necessary for an agent to select and call the tool correctly.

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

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

Schema description coverage is 100%, since the emails parameter is already described as 'Emails to resolve.' The tool description adds the purpose of returning display names, but provides no additional parameter-level format, validation, or edge-case guidance beyond what the schema already states.

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, 'Resolve', and names the exact resource ('public display names') and input ('a set of emails'). It fully distinguishes this tool from sibling tools like get_board or get_org, which serve entirely different purposes.

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 intended context is implied: use this tool when you have emails and need public display names. There is no explicit mention of alternatives or when not to use it, but no sibling tool performs a similar email-to-display-name resolution, so the omission is less critical.

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?

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds useful behavioral nuance beyond the schema: only published templates are accessible, free templates expose a project id while paid ones deliberately do not, and the reason is that the schema is the product. This goes beyond the structural return data.

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

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

The description is two sentences with no filler. It front-loads the core purpose and return contents, then adds the free-versus-paid distinction, which is valuable and directly affects how an agent interprets the response. 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?

With one required parameter, a fully documented schema, an output schema, and readOnly annotations, the description is largely complete. It explains the return payload and the crucial free/paid behavioral difference. It could have explicitly pointed to browse_templates as the way to discover slugs, but that is a minor omission given the available sibling tools.

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 slug parameter is already documented as the listing slug as it appears in the public URL. The description reinforces that the slug identifies a template, but it does not add meaning beyond the schema, 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 ('Get'), a resource ('one published template'), and a selector ('by its slug'), then enumerates exactly what is returned: description, table names, foreign-key graph, and counts. It also clarifies a meaningful distinction between free and paid templates, which helps separate this tool from browse_templates and template_categories.

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 implies the tool is for retrieving a single published template when you already know its slug, and it excludes unpublished templates by using 'published'. It does not explicitly name sibling tools like browse_templates for listing or template_categories for category browsing, so the when-not-to-use guidance is only implicit rather than 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?

Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds useful behavioral context: it summarizes counts and diagram types without exposing document content, and it implies a low-cost overview operation useful for triage.

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 deliver the core outcome, the key exclusion, the return detail (Mermaid types), and usage guidance. Every part earns its place and the main behavior is front-loaded.

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

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

The tool is simple, has one fully described parameter, read-only annotations, and an output schema. The description covers what is returned, what is excluded, and how to use it, so nothing essential 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 descripption coverage is 100% and the single projectId parameter is fully documented in the schema. The description adds no additional parameter-level detail, 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 states a specific verb ('Summarise'), resource ('a project'), and scope ('by kind, without any document content'), including exact counts and Mermaid types. It also distinguishes itself from list_documents by explicitly saying what it does not include.

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

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

The description gives explicit when-to-use guidance: 'Call this before list_documents to decide what is worth reading.' This clearly positions the tool relative to its sibling and tells an agent when it is the right choice.

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

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

The readOnlyHint annotation already covers the safety profile, so the description only needs to add non-obvious behavior. It discloses that documents carry a kind, that kinds include dbml and mermaid, and that both render on the same board, which is valuable context beyond the annotation.

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, information-dense sentences with no wasted words. The core action and scope are front-loaded, and the additional detail about kinds 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 well-documented parameter and an existing output schema, the description is complete enough. It conveys what is returned, the ordering trait, and the semantic distinction between document kinds without over-explaining.

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 100% schema description coverage and a single projectId parameter documented as 'Project id (uuid).', the schema already fully explains the parameter. The description does not add any additional semantic details about the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('a project's documents') and adds useful detail about content, ordering, and document kinds. It distinguishes the tool from sibling listing tools by focusing on documents rather than diagrams, drawings, or tables, though it does not explicitly name 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?

The description gives a clear context for use: listing a project's documents with their content, ordered, and explains the kinds of documents returned. It does not explicitly state when not to use this tool or name alternatives like list_diagrams, but the intended use case is clear.

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

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

Annotations already indicate readOnlyHint=true, matching the description's read-only nature. The description adds behavioral context beyond annotations by disclosing that point lists are intentionally omitted and summarizing what fields are returned, which helps set expectations for downstream use.

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 with no filler: the first defines functionality and output fields, the second gives a concrete use case and names the alternative. Information is front-loaded and 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 one-parameter read-only list tool with an output schema present, the description is fully sufficient. It explains what data is included, what is omitted, and when to use a sibling tool. No critical information 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%, with projectId described as 'Project id (uuid).' The tool description does not add additional parameter semantics, but the schema already adequately documents the only parameter, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Summarize') and resource ('a project's drawings') while explicitly listing the returned fields, making the tool's function immediately understandable. It clearly distinguishes itself from get_board, which is named as carrying the full geometry.

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

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

The description explicitly states when to use this tool: 'Use this to find a stroke to erase.' It also names the alternative, get_board, and explains why you would choose that instead. This gives the agent clear 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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context beyond that: it includes drafts, includes admin-removed listings with the removal reason, and carries linking ids for downstream mutation tools. This is meaningful extra information.

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 with no filler. The core purpose is front-loaded, and the second sentence adds only the high-value details about returned identifiers and included states.

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

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

For a zero-parameter read-only listing tool with an output schema and readOnlyHint annotation, the description is complete. It explains scope, included items, special content (taken-down reason), and how the results connect to sibling tools.

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

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

The tool has zero parameters, so the description carries no parameter-documentation burden. The baseline of 4 applies because there is nothing for the description to explain about parameters.

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 begins with a specific verb and resource: 'List the templates the signed-in user has published.' It adds precise scoping (drafts, admin-taken-down listings with reasons) that distinguishes it from public browsing tools like browse_templates and from get_template.

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 implies the tool is for the signed-in user's own published templates and explains that it returns the listing ids needed for update_listing and unpublish_listing. It provides clear context but does not explicitly state when not to use it or name browse_templates as the alternative for public templates.

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?

Annotations already declare readOnlyHint=true, and the description adds genuinely useful behavioral context beyond that: results are restricted to orgs the signed-in user belongs to, and ordering places the personal org first. These are behavioral traits not encoded in the annotations. No contradiction with openWorldHint=false — the membership scope actually reinforces the closed-world stance.

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 sentence, 13 words, front-loaded with the verb and resource, with the ordering detail tucked cleanly into a parenthetical. Every word carries information; there is zero waste or repetition of the title beyond the necessary verb.

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 0-param read-only list tool with an output schema present, the description covers purpose, scope, and ordering completely. An agent knows exactly what will happen and what it will get. The only conceivable addition — routing to get_org for single-org details — is a nice-to-have, not a gap at 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?

The tool has 0 parameters and schema description coverage is 100%, so there is nothing for the description to explain. Per the rubric, 0 params earns a baseline 4; the description correctly devotes no space to parameters.

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'), resource ('organizations'), and scope ('the signed-in user belongs to') in one sentence. The parenthetical 'personal org first' adds ordering detail that further pins down behavior. This clearly differentiates it from siblings like get_org, create_org, and delete_org without needing to open 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?

The scope clause 'the signed-in user belongs to' provides clear context for when to invoke this tool — when the agent needs the current user's org membership list, not a specific org (get_org) and not a mutation (create_org/delete_org). It doesn't explicitly name alternatives or exclusions, but the context is unambiguous for a 0-param list tool.

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?

Annotations mark the tool as readOnlyHint, so no mutation is implied. The description adds useful behavioral context beyond annotations: results are filtered by the signed-in user's visibility, and the response includes the caller's effective role, which is auth/permission-relevant information not present in the 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?

Single sentence, front-loaded verb and resource, and includes only essential qualifiers. No redundant information 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?

Given the simple input (one UUID), the presence of an output schema, and the readOnly annotation, the description covers everything an agent needs: scope, visibility filter, and return highlights. Nothing significant 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?

The only parameter, orgId, has a complete description in the schema (type string, format uuid). Schema description coverage is 100%, so the description need not add parameter semantics. It doesn't, which is acceptable at the baseline.

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

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

The description uses a specific verb ('List') and resource ('projects in an organization'), and narrows scope with 'that the signed-in user can see.' It also previews returned fields (document count, members, effective role), making the tool's function unambiguous and distinct from siblings like list_orgs 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 description clearly identifies the operation context: listing projects within an organization, scoped to what the signed-in user can see. It doesn't explicitly name alternatives or exclusions, but the context is sufficient for the common case and the sibling set makes the right tool obvious.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond that: it explains that the returned id matches keys in get_board's positions map, and that the tool lists only tables 'declared' by documents, which clarifies the data scope and helps the agent interpret results.

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

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

The description is compact and front-loaded: the first sentence states what the tool returns, and the second sentence explains the id relationship and provides practical usage guidance. Every phrase adds value without unnecessary 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-parameter read-only tool with an output schema, the description is complete. It names the output fields, connects the id to get_board's positions map, and gives clear use cases. Annotations cover the read-only safety profile, and the schema covers the parameter, so nothing essential 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% and the single parameter projectId is documented in the schema as a uuid. The tool description does not add additional parameter-level detail, but none is needed because the schema fully explains the parameter; 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 ('List') and resource ('the tables a project's documents declare') and enumerates the exact fields returned, including id, name, schema, owning document, header color, and field count. This clearly differentiates it from sibling tools like list_documents and get_board by focusing on table-level metadata.

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

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

The description gives explicit use cases: 'Use this to find a table before recoloring it, or to see which document owns it.' This provides clear context for when to call the tool, and the reference to set_table_color and get_board helps an agent choose it appropriately, though it does not explicitly state when not to use it.

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

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

Annotations already mark the tool as destructive, and the description meaningfully expands on that: it discloses public internet readability of the schema and, for free templates, the live board; it also details the refusal behavior for org admins. It adds material context beyond the annotation without contradicting it.

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

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

The description is compact yet information-dense, front-loading the core purpose and then covering permission, consequences, confirmation, and pricing in logical order. Every sentence contributes actionable guidance 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 publishing action with a destructive hint, the description covers the critical context: who can act, what becomes public, the need for user confirmation, and the pricing note. An output schema exists, so return-value details are unnecessary. Nothing an agent needs to decide or warn about 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. The description adds valuable context beyond the schema, such as the permanent public web address derived from the title on first publish and the marketplace-card subtitle role of the summary. This helps the agent choose correct parameter 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 opens with a specific verb and resource: publish one of the user's projects to the public template marketplace, or re-publish an existing listing. It clearly identifies the input (PROJECT id) and is easily distinguished from sibling tools like update_listing and unpublish_listing.

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

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

The description explicitly states who may call it (only the project creator) and instructs to confirm with the user before invoking. It does not name alternative listing-management tools, but the permission context and public-exposure warning give clear conditions for appropriate use.

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

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

The description simply restates the destructive action already conveyed by the name and destructiveHint annotation. It does not disclose important behavioral implications such as whether the removal is irreversible, whether the underlying user account is affected, or permission/role restrictions.

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

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

The description is a single concise sentence with no filler. The core action, scope, and identification method are front-loaded and easy to parse.

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 destructive tool, the description is minimally viable, especially with an output schema and destructiveHint annotation available. However, it lacks edge-case guidance such as whether the last owner can be removed, whether deletion is permanent, or what happens when the email does not match 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 description coverage is 100%, so the schema fully documents orgId and email. The description adds only that email is the identifying field, which is already implied by the schema description, providing marginal semantic value.

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') and resource ('one member from an organization') and identifies the email parameter as the lookup key. It clearly differentiates from project-member tools by specifying organization, though it does not explicitly name sibling 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?

No guidance is given for when to use this tool versus alternatives such as remove_project_member or upsert_org_member. An agent must infer the scope from the word 'organization' rather than being told directly.

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?

Annotations already declare destructiveHint=true, which aligns with the description's 'Remove' verb and leaves no contradiction. The description adds some scoping context ('one member', 'by email') but does not disclose any further side effects such as access revocation, reversibility, or permissions required. With the annotation already carrying the destructive signal, this level is acceptable.

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

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

The description is a single, front-loaded sentence with no filler. Every word earns its place, and the core action and target are immediately clear.

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, single-actor mutation tool, the description is sufficiently complete. The schema provides full parameter documentation, destructiveHint covers the safety profile, and an output schema is present, so nothing essential is missing for selecting and invoking the 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 the baseline is 3 even if the description provided no additional parameter meaning. The description's 'by email' slightly reinforces the email parameter's role, but it does not add substantially beyond the schema's 'Member email address.' description.

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

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

The description uses a specific verb ('remove'), a clear resource ('project member'), and the identifying method ('by email'). It is unambiguous and effectively distinguishes this tool from siblings like remove_org_member or upsert_project_member by specifying project membership.

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 implies when to use this tool: when removing a single member from a project by their email address. However, it does not explicitly contrast with alternatives such as remove_org_member or upsert_project_member, nor does it mention when not to use it.

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

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

Annotations already include destructiveHint=true, which covers the mutation risk. The description adds the 'personal org is frozen' constraint, which is useful behavioral context. However, it does not explain side effects, reversibility, or what happens if attemted on a frozen org, so it only partially goes beyond the annotations.

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

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

The description is a single, efficient sentence that states the operation and the key restriction in an immediately digestible way. Every word contributes meaning, with no filler or unnecessary detail.

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 low-complexity tool with two required parameters, full schema coverage, a destructiveHint, and an output schema, the description is nearly complete. It covers the core operation and the main caveat. The only minor gap is not explicitly spelling out that the personal org cannot be renamed as a direct instruction, but the parenthetical conveys this adequately.

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 both 'name' and 'orgId' clearly. The description adds no additional parameter-level detail, such as format constraints or relationship between parameters. 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 states a specific verb ('Rename') and resource ('organization'), which clearly identifies the operation. It also adds a meaningful constraint ('the personal org is frozen') that distinguishes this from generic org management operations and prevents misuse. The sibling-tool set further confirms this is the dedicated rename 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 description provides clear context: use this to rename an organization, but not a personal org because that org is frozen. It does not explicitly list alternative tools, but given the siblings, no direct alternative for renaming exists. The frozen-org note acts as a useful 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?

Annotations already declare destructiveHint=true, so the description does not need to rehash destructiveness. It adds meaningful behavioral context by stating that the operation is atomic, implying all order changes succeed or fail together. This goes beyond the structured annotations without contradicting them.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the core action, the target resource, and the atomicity guarantee while remaining highly readable. Every word 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?

Given the presence of a rich input schema, output schema, and annotations, the description covers the essential behavioral nuance (atomicity) without duplicating structured information. It could theoretically mention that only changed documents need to be included, but the updates property description already covers that, so 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?

The input schema has 100% description coverage for both projectId and updates, so the schema already explains the parameters well. The description adds no additional parameter-level detail, which is acceptable given the high schema coverage but not a value-add.

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 and resource ('set the sort order of documents') and adds an important qualifier ('in one atomic transaction'). This distinguishes it from broader document mutation tools like update_document by focusing on ordering behavior, making the tool's purpose immediately clear.

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

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

The description clearly implies the tool is for changing document sort order, but it does not explicitly state when to use this tool versus alternatives such as update_document or create_document. There is no when-not-to-use guidance or sibling differentiation beyond the semantic meaning of 'sort order'.

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?

DestructiveHint is already true, so the description builds on that: it reveals that the color lives in DBML, edits the sourced document, and is visible to every collaborator. This is valuable side-effect disclosure beyond the annotation, though it doesn't delve into undo/rollback or failure modes.

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 concise sentences, each earning its keep: the core behavior, the persistence effet, and a workflow recipe. No redudant or 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 simple setter with an output schema, the description adequately covers purpose, side effects, and surrounding workflow. It doesn't discuss permissions or edge cases, but the destructiveHint plus persistente context makes the operational impact clear enough for an agent to proceed.

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 covers all three parameters at 100%, so baseline is 3. The description supplements by giving a concrete color example (#f6d55c), clarifying the table parameter with a discovery path via list_tables, and emphasizing the null/omission behavior. This adds practical meaning beyond the schema.

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

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

The description clearly specifies the action ('Set a table's header color') and the resource (table), and includes the important nuance of passing no color to clear it. This differentiates it well from sibling tools like list_tables or get_board_image.

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 explicit workflow guidance: use list_tables to find the table id, and pair with get_board_image to observe the result. It stops short of naming disfavored alternatives or specifying when not to use it, but the context is clear enough.

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?

Beyond the destructiveHint annotation, the description reveals important behavioral details: copies made by others remain theirs, the project becomes private again, and the same public address is reused on re-publishing. These are exactly the non-obvious side effects an agent needs to know.

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 tightly written sentences, each carrying substantive information: the core action, ownership scope, and post-action behavior. There is no repetition of the schema or annotations, and the most important information is front-loaded.

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

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

This is a single-parameter tool with an output schema and annotations, so the description already covers everything needed for correct invocation. The ownership constraint and copy/address semantics are the kinds of details that prevent misuse, and they are present.

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

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

The input schema already fully documents the only parameter, listingId, and even sources it from list_my_listings. With 100% schema description coverage, the description does not need to add parameter-level detail; 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 states a specific action: take one of the user's own templates off the marketplace and make its project private again. This clearly differentiates it from siblings like publish_listing and update_listing without requiring the agent to inspect their schemas.

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

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

The description gives clear context: it applies only to the user's own templates, and it notes that re-publishing later reuses the same public address, implying the inverse use of publish_listing. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for correct selection.

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

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

The annotation destructiveHint=true already signals mutation, but the description goes further with precise semantics: omitted ids are left unchanged, null deletes, and notes is stored whole. This accurately discloses the destructive and merge-like behavior of the tool beyond what annotations provide.

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 three sentences, front-loads the core merge concept, and each sentence earns its place. It states the key behavioral rule, the whole-notes exception, and the drawing-tool alternative without redundancy 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?

Given destructiveHint, 100% schema coverage, an output schema, and a rich sibling list, the description covers the essential merge/delete semantics and alternative routing. An agent has enough information to call update_board correctly and avoid destructive mistakes.

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 valuable cross-cutting semantics not present in the individual parameter descriptions: the omitted-vs-null distinction across all id-keyed families and the 'notes is stored whole' rule. This lifts it above baseline.

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

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

The description opens with 'Merge a partial board delta', a specific verb+resource statement that clearly explains what the tool does. It also differentiates from siblings by explicitly steering drawings to draw, draw_shape, and erase_drawings, so an agent can distinguish it from related board-editing tools without opening each 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 description establishes the partial-update usage pattern ('Provide only the ids you are changing') and gives explicit routing guidance for drawings ('For drawings prefer draw, draw_shape and erase_drawings'). The images parameter schema further points to add_board_image, covering the main alternative cases, though the description itself does not consolidate all 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 destructiveHint=true already signaling mutation, the description adds useful partial-update semantics: 'Omit a field to leave it unchanged.' It does not expand on irreversibility, permissions, or the fact that content replacement is a full overwrite, but annotations lower the burden.

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 that immediately communicates the operation and the key partial-update 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?

The description is minimally adequate for a simple update operation, but it leaves gaps: it does not mention that kind and order are also updatable, and it gives no routing information relative to reorder_documents or delete_document. The output schema and annotations cover some other context, lowering the burden on the 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 description coverage is 100%, so parameters are already well documented. The description's 'omit a field' guidance adds a small layer of meaning, but it also omits two updatable fields (kind and order), reducing its value as a summary.

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 clear action and resource: 'Update a document's name and/or content.' This distinguishes it from create_document and delete_document at a basic level. However, it mentions only name and content while the schema also allows updating kind and order, so the stated scope is incomplete.

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

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

No guidance is given about when to choose this tool over siblings like reorder_documents or delete_document. The only usage hint is 'Omit a field to leave it unchanged,' which addresses parameter semantics rather than tool selection.

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?

Beyond the destructiveHint annotation, the description discloses two non-obvious behaviors: the public web address is fixed at first publish and does not follow title changes, and fields are replaced wholesale so unsent fields will be lost. These are exactly the behavioral details an agent needs before calling.

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, each load-bearing: the first defines scope and fields, the second pins the identifier source, and the third conveys two critical replacement and URL behaviors. There is no filler and the most important information is front-loaded.

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

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

Given the rich input schema, output schema, and annotations, the description covers all essential traps for invoking the tool correctly: the correct id source, the wholesale replacement behavior, and the stable public URL. 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantic value by warning that every field is replaced by what is sent and that the listing id must be a LISTING id, not a project id. This goes beyond the per-field schema documentation.

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

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

The description opens with a specific verb and resource: 'Edit a published listing's text' and enumerates the exact fields involved: title, summary, description, category, tags. It also disambiguates the identifier by saying it takes a LISTING id from list_my_listings, 'not a project id,' which separates this tool from project-related 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 provides clear context: use this tool to edit a published listing's text, and the listing id must come from list_my_listings rather than a project id. It does not explicitly name publish_listing/unpublish_listing as alternatives, but the context is strong enough to guide selection.

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?

Annotations already declare destructiveHint=true, and the description aligns with that by indicating a mutation. It adds partial-update context ('name and/or sort order' implies other fields are untouched), but it does not disclose reversibility, permissions, or downstream effects. Given annotation coverage, this is adequate but not rich.

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 concise, front-loaded sentence with no filler. Every word contributes to identifying the operation and its scope.

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 update tool with full schema coverage, an output schema, and annotations carrying the destructive hint, the description is nearly complete. The only notable gap is lack of sibling differentiation guidance, but the resource name and scope make correct invocation straightforward.

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

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

The input schema covers all three parameters with descriptions and defaults, so schema coverage is effectively 100%. The description mainly paraphrases the 'order' parameter as 'sort order' and adds little meaning 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 the explicit verb 'Update' with the resource 'project' and the exact scope ('name and/or sort order'). This distinguishes it from sibling update_* tools like update_board or update_document by naming the target resource, rather than merely restating the title.

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 no when-to-use guidance, no exclusions, and no alternatives. With many update_* siblings present, the agent gets no explicit routing signal beyond the resource name in the tool itself.

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

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

The destructiveHint annotation already signals mutability, and the description adds that the operation is keyed by email and limited to specific roles. However, it does not explain whether an existing member's role is replaced, merged, or created only if absent, leaving the 'update' semantics ambiguous.

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 primary action and identifier key (email) are front-loaded, and the role restriction is stated compactly. Every phrase 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 3-parameter tool with a complete schema and an output schema present, the description is mostly sufficient. The only notable gap is the precise upsert behavior (create vs. update semantics), which is not fully disclosed, but this is a minor omission given the low complexity.

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?

Input schema covers all three parameters with 100% description coverage, so the description adds nothing beyond what the schema already provides. The role list is redudant with the role parameter description, and no new parameter-level context is introduced.

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

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

The description clearly states the operation: 'Add or update one organization member by email', identifying a specific verb and resource. It does not explicitly distinguish itself from sibling tools like upsert_project_member, but the org scoping is clear enough for basic selection.

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

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

The description implies the tool is for org-level membership management by email, but it does not state when to prefer this over alternatives like remove_org_member or upsert_project_member. There is clear context but no explicit exclusions or 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?

Annotations already signal destructiveHint=true, so the description does not need to restate that. It adds useful semantics by clarifying the upsert behavior: match by email and either add a new member or update the existing member. It does not describe failure modes, permission needs, or role overwrite specifics, but the annotations cover the core safety profile.

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 filler. It front-loads the primary action and resource, then provides the allowed role values in a compact list. 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?

Given a simple 3-parameter tool, full schema documentation, an output schema, and annotations that flag destructiveness, the description is nearly complete. It captures the core upsert semantics and role constraints. The only missing part is explicit usage guidance relative to sibling tools, which is already penalized in usage_guidelines.

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 each parameter already has a description, so baseline is 3. The description adds meaningful extra semantics by stating 'by email', which identifies email as the matching key for the upsert rather than just a field to set. The listed roles duplicate the schema but are still useful.

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 ('Add or update') and resource ('one project member'), and identifies the lookup key ('by email') plus allowed roles. It clearly conveys what the tool does, but it does not explicitly differentiate itself from siblings like upsert_org_member or remove_project_member beyond the resource name.

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

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

The description implies when this tool is appropriate—when a caller needs to add or update a single project member by email. However, it provides no explicit guidance about when not to use it, such as when to use remove_project_member or upsert_org_member instead.

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

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

The description goes beyond the annotations by disclosing that the copy is independent and later changes by the template author do not reach it. It also states that documents and board are included in the copy. This is valuable behavioral context that the agent would not otherwise know from openWorldHint or destructiveHint.

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 deliver the core action, the behavioral independence guarantee, and a critical usage instruction. The most important information is front-loaded, and every sentence earns its place without fluff.

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

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

Given that the output schema exists and the input schema is fully documented, the description is complete enough for an agent to select and invoke this tool correctly. It explains what gets copied, that the copy is independent, and how to resolve the one ambiguous input (orgId) by pointing to list_orgs.

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 name, slug, and orgId adequately. The description adds practical guidance that orgId should be obtained via list_orgs rather than guessing, which is helpful, but it does not add substantial new meaning to the parameters themselves beyond what the schema already 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 states a specific verb ('Copy'), a specific resource ('a published template'), and the result ('into one of the user's organizations as a new project, with its documents and board'). This clearly distinguishes it from sibling tools like browse_templates or get_template, which only read or browse templates.

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

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

The description gives clear context: use this to copy a published template into an organization. It also tells the agent to ask which organization to use rather than guess, and explicitly points to list_orgs for ids. It does not, however, explicitly mention when to prefer create_project or browse_templates instead, so it lacks explicit 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?

Annotations already indicate this is a read-only, non-open-world operation, so the description does not need to restate safety. It adds value by specifying that the returned data is the profile of the signed-in user, which is useful behavioral context beyond the tool name.

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

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

The description is a single sentence with no filler. It front-loads the action ('Return') and immediately specifies the resource, making it maximally efficient for an agent to parse.

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, zero-parameter, read-only tool with an output schema available, the description provides all necessary context. An agent can safely infer the tool's purpose and know that no arguments are required.

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

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

The tool has zero parameters, so there is no parameter meaning for the description to explain. The baseline for zero-parameter tools is 4, and the description correctly focuses on the output rather than inputs.

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 ('Return') and identifies the exact resource: the signed-in user and their profile. This clearly distinguishes it from sibling tools like get_public_profiles, which return other users' profiles rather than the current authenticated user.

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 makes clear that this tool is for retrieving the current signed-in user's identity, which is sufficient context for an agent to know when to use it. It does not explicitly contrast it with alternatives like get_public_profiles, but the 'signed-in' qualifier implies the distinction.

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