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 provide readOnlyHint=true and openWorldHint=false. The description adds that the tool returns only published listings and includes counts and a category breakdown, useful behavioral context beyond the annotations. No contradiction with 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?

Two sentences with no filler. The first sentence states the action, and the second adds behavior and a use case. The key scoping ('published listings only', 'counts and a category breakdown') 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 low-complexity read-only search tool with all optional parameters documented and an output schema present. The description covers the key behavioral scoping—published only, counts, category breakdown—and gives a concrete usage context. Nothing essential for correct invocation is missing.

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

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

All 6 parameters have full schema descriptions covering their semantics, so the baseline is 3. The description does not add parameter-level information, but it does not need to because the schema already 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 opens with 'Search the public template marketplace,' naming a specific verb and resource. It further differentiates the tool from siblings by stating it 'Returns published listings only, with counts and a category breakdown,' clearly separating it from get_template, template_categories, and my_listings.

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 an explicit use case: 'Use it to find a schema to start from before writing DBML by hand.' This provides clear context for when to use it. It does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

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?

The description adds meaningful behavioral detail beyond annotations: points are vertices, not a sampled path, the head is drawn on the last segment, and 2 to 50 vertices are allowed. This clarifies an important non-obvious behavior that could affect how an agent constructs correct input.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds value. It explains the most important semantic detail about vertices without redundancy or 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?

For a drawing tool with an output schema and a clear safety profile in annotations, the description covers the essential behavior, parameter constraints, and return value. It does not discuss prerequisites like project existence, but that is a minor gap given the schema and output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description significantly enriches the meaning of the 'points' parameter by explaining vertices, straight vs. bent arrows, and head placement. This goes beyond the schema's 'at least two' and materially helps an agent build valid calls.

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 ('Draw one arrow on a project's board') and a concrete result ('return its id'). It clearly distinguishes this from siblings like draw_stroke by specifying arrow-specific geometry and terminology.

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 communicates the core use case but does not explicitly contrast with alternatives such as draw_stroke or explain when to prefer this tool. Usage context is implied through the tool name and description rather than made 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 annotations provide only openWorld/structive hints, so the description carries responsibility for behavioral detail. It adds concrete behavior: returns the stroke id, interprets points as board world coordinates, rounds storage to 2 decimals, renders a single point as a dot, and caps input at 1000 points. This goes well beyond the structured annotation 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 concise and front-loaded: first sentence states the purpose and return value, and the following sentences add only essential detail about coordinate formats, storage behavior, and limits. No words are wasted.

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

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

Given a moderately complex input schema and an output schema that exists, the description covers the key invocation facts: coordinate system, point formats, rounding, max points, and the returned id. It does not articulate alternative-selection guidance or permissions, but those are less critical for a non-destructive drawing tool with well-described parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: points are board world coordinates, accepted formats are echoed for the points parameter, and constraints such as rounding and the 1000-point limit are stated. These are important for correct invocation.

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

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

The description opens with a specific verb and resource: 'Draw one freehand marker stroke on a project's board and return its id.' This clearly identifies the action, the target, and the output, and it naturally distinguishes the tool from siblings like 'draw_arrow' and 'erase_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?

The description implies use for freehand marker strokes rather than arrows or other drawing tools, but it never explicitly states when to use this tool versus alternatives. There is no 'use when' or 'use instead' guidance, so the agent must infer the boundary from the word 'marker' and sibling names.

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

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

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, 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?

The description adds the visibility scoping detail (signed-in user can see), which complements the readOnlyHint annotation. With the safety profile already declared by annotations, this description provides modest behavioral context but no additional traits like pagination or return format.

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

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

A single, front-loaded sentence with no redundancy. Itefficiently communicates the core operation, scope, and visibility filter without wasting tokens.

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 one-parameter read-only operation, an output schema for return values, and annotations covering the read-only hint, the description is complete enough for an agent to invoke it correctly. 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 already fully describes orgId as a UUID with a clear meaning, so the description does not need to add parameter detail. The tool-level description does not go beyond the schema, but the baseline of 3 applies due to 100% schema coverage.

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

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

States a specific verb ('List') and resource ('projects in an organization that the signed-in user can see'), clearly distinguishing it from sibling list tools like list_orgs, list_diagrams, or list_documents. The scope is precise: projects, scoped to an organization and filtered by user visibility.

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 context: you need the organization ID and you only get projects the signed-in user can see. However, it does not explicitly say when to choose this tool over alternatives, nor does it mention exclusions or prerequisites beyond the orgID parameter.

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?

With readOnlyHint=true already in annotations, the description adds useful behavioral context beyond the hint: results include drafts and admin-taken-down templates with reasons, and returned objects carry listing IDs and project IDs. This meaningfully informs an agent about what the response will contain.

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 high-value linkage to sibling mutation tools. Every sentence earns its place.

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

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

For a simple, parameterless read-only listing tool with an output schema, the description is complete. It states the scope, the included edge cases (drafts, admin removals), the reason field, and the IDs the caller will need for follow-up operations.

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 schema burden for the description to carry. The description's mention that results carry listing IDs and project IDs is relevant to downstream invocation of update_listing and unpublish_listing, even though no input parameters are required here.

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 ('List'), a resource ('templates the signed-in user has published'), and clarifies scope by including drafts and admin-taken-down items. It clearly differentiates this personal-list tool from sibling tools like browse_templates, which are for browsing templates generally.

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: this is for retrieving the signed-in user's own published templates and for obtaining listing IDs used by update_listing and unpublish_listing. It does not explicitly say when not to use it versus browse_templates, but the personal-scope language makes the intended use 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?

The description is consistent with the readOnlyHint annotation and adds the aggregate-per-project-id behavior. However, it does not disclose edge cases such as how invalid or missing project IDs are handled. Since annotations already cover the read-only safety profile, 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?

The description is a single, focused sentence with no filler. It front-loads the action and resource immediately, and 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 simple one-parameter read-only aggregate tool with full schema coverage and an output schema present, this description is complete enough. An agent can correctly select and invoke the tool without missing critical context.

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 parameter is already clearly described as 'Project ids (uuids).' The description only restates this concept ('given project ids') without adding format, defaults, or validation details, so the schema carries the semantic load.

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'), names the resource ('document count'), and scopes it to 'each of the given project ids.' This clearly distinguishes it from sibling tools like list_documents (which lists documents) and list_projects (which lists projects).

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 intended use case: when you need aggregate document counts for specific project IDs. It does not explicitly name alternatives or exclusions, but the context is unambiguous for a simple read-only 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?

The description goes well beyond the destructiveHint annotation by explaining the real-world consequences: the schema and live board become internet-readable, the action may be a re-publish, and non-creators are refused even if they can otherwise edit. It also notes pricing considerations and directs the agent to server instructions.

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 every sentence earns its place: purpose, permission restriction, public visibility consequence, confirmation requirement, and pricing note. The most important information is front-loaded in the first sentence.

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

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

Given the tool's destructive/public-exposure nature, the description covers the critical operational facts: who may call it, what to confirm with the user, what becomes public, and how re-publishing behaves. The output schema supplies return-value details, 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 the schema already documents all six parameters. The description adds minimal parameter-specific meaning beyond noting that it takes a PROJECT id and that the title's derived address is permanent, which is useful but not enough to raise the score 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 a specific verb and resource: publishing a project to the public template marketplace, and explicitly includes the re-publish case. This clearly distinguishes it from related tools like update_listing or unpublish_listing by focusing on the publishing action.

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: only the project creator may publish, and the agent must confirm with the user before calling due to public exposure. It does not explicitly name alternatives or state when not to use the tool, but the conditions and prerequisites are strong enough for an agent to decide appropriately.

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?

With readOnlyHint=true and openWorldHint=false already declaring safety and closed-world semantics, the description adds useful context: it identifies the vocabulary as canonical for two specific sibling tools and asserts the slugs are exact. This goes beyond a generic read-only label without contradicting 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?

A single, front-loaded sentence conveys the tool's identity and its relationship to sibling tools with zero filler. 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 zero parameters, a read-only annotation, and an output schema, the description contains all necessary selection and usage context. The output shape is covered by the output schema, 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?

No parameters exist, so there is nothing to document; the baseline for a zero-parameter tool is 4. The description's mention of accepting slugs pertains to sibling tools rather than input parameters, which is appropriate for this no-input lookup.

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

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

The description identifies the resource as the template category vocabulary and states its exact purpose: the slugs accepted by browse_templates and publish_listing. It does not use an explicit verb like 'list' or 'return', so it falls just short of a 5, but it clearly distinguishes this tool from siblings by naming its two consumers.

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 sentence makes plain when an agent needs this tool: when preparing category values for browse_templates or publish_listing. It doesn't explicitly say when not to use it or name alternatives, but the consumer linkage provides clear context for 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 annotations already mark this as destructive, and the description adds meaningful behavioral context beyond that: the project is made private, copies made by others remain with their creators, and republishing later reuses the same public address. These are important side effects an agent should know before invoking the 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 three short sentences with no filler. The primary action is front-loaded, followed by two concise caveats that clarify persistence and future behavior. Every sentence earns its place.

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

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

For a single-parameter mutation with an output schema present, the description covers the core action, consequences for existing copies, reversibility, and the reuse of the public address. Nothing essential is missing for an agent to understand when and how to call this 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?

The input schema already fully documents the only parameter, listingId, including its UUID format and that it comes from my_listings. The description adds the ownership nuance ('user's own templates'), but since schema coverage is 100%, the description is not required to compensate for missing parameter details.

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 ('Take ... off the marketplace') and resource ('one of the user's own templates'), and clearly distinguishes it from its sibling publish_listing by describing the reverse action. It also clarifies the effect on project privacy, leaving no ambiguity about what the tool does.

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

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

The context is clear: this tool is for removing a user's own template from the marketplace, and the final sentence mentions re-publishing, implicitly contrasting it with publish_listing. It does not explicitly list alternatives or say when not to use it, but the single purpose is stated well enough for an agent to select it correctly.

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 deletion behavior is expected. The description adds precise destructive semantics: null deletes an id, omitted id is left unchanged, and notes is stored whole. This meaningfully expands on 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?

Three densely informative sentences, front-loaded with the core merge rule, then null semantics, then notes, then alternative tool routing. Every sentence earns its place and there is no filler.

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

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

Given the complex delta tool, an existing output schema, and 100% schema description coverage, the description covers the remaining critical context: partial merge behavior, delete semantics, notes handling, and when to use sibling drawing tools. An agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds cross-cutting parameter behavior that individual schemas don't fully convey: omitted vs null per id in all id-keyed families, and the whole-store semantics for notes. This goes beyond what the property descriptions already provide.

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 identifies the operation as a partial update to a board. The title 'Update board layout' reinforces the resource. It also distinguishes itself from drawing-specific siblings by directing drawings to draw_stroke, draw_arrow, and erase_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 explicit when-to-use guidance: provide only changed ids, omitted ids are unchanged, null values delete. It also explicitly says to prefer draw_stroke, draw_arrow, and erase_drawings for drawings, naming the alternatives. This is strong routing guidance beyond mere tool intent.

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?

The annotations only mark destructiveHint=true; the description adds crucial behavioral context beyond that: full replacement semantics ('Every field is replaced by what is sent, so send the ones being kept as well as the ones being changed') and a side effect ('public web address is fixed at first publish and does not follow a title change'). This gives the agent a realistic mental model of the mutation.

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?

Four sentences, each carrying distinct information: scope, id source, link stability, and replacement behavior. No filler or redundancy, and the most important action verb is front-loaded. Every sentence earns its place.

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

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

For a 6-parameter mutation tool with an output schema and destructiveHint annotation, the description covers the essential operational details: what the tool edits, how the id is obtained, what parameters are affected, and how replacement behaves. The existence of an output schema means return values don't need description-level detail. 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 already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful value by clarifying that listingId must come from my_listings and is not a project id, and by explaining that all sent fields replace current values, which affects how every parameter is interpreted. This goes beyond simple schema repetition.

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 ('Edit'), a specific resource ('published listing's text'), and enumerates the editable fields ('title, summary, description, category, tags'). Also distinguishes it from related tools by noting it takes a LISTING id not a project id, which clearly separates it from update_project and similar 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?

Provides clear when-to-use context: 'Edit a published listing's text' and explicitly warns against using a project id, instead directing to my_listings. It does not name alternative tools explicitly, but the id-source guidance effectively excludes the wrong tools, and the 'Every field is replaced' note tells the agent how to behave. Missing a direct 'use this instead of publish/unpublish' statement keeps it from a 5.

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

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

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.