FeatureBoard MCP Server

by valentil

Overview Schema Related Servers Score Discussions

JavaScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.9.3
Disambiguation4/5
Despite 215 tools, each has a detailed description that clarifies its distinct purpose. Some overlap exists among UI-returning tools (get_board vs get_rag_explorer) and export tools, but descriptions mitigate ambiguity.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., list_tasks, create_campaign, add_decision). No mixing of conventions.
Tool Count2/5
215 tools is extremely high for a single MCP server. While the scope is broad (project management, CRM, marketing, etc.), many tools feel like feature creep rather than essential. A more focused set would improve coherence.
Completeness4/5
The toolset covers an impressively wide range of operations across many domains. Minor gaps exist (e.g., no delete_project, no delete_company), but core workflows are well-supported.
Average 4/5 across 215 of 215 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 228 commits in the last 12 weeks
- Last stable release on August 25, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms a destructive action, which matches the destructiveHint=true annotation. However, it does not disclose any additional behavioral traits such as whether the deletion cascades to related licenses or requires specific permissions, leaving gaps that annotations don't cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but omits necessary details about parameters and usage. It earns its place but should be slightly expanded without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a destructive action, the description should provide more context about consequences or prerequisites. Currently, it is too minimal to fully inform an agent's decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden but fails to explain any of the three required parameters (id, company, project). It only mentions 'by id' but does not specify the roles of other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a contract/license from a company by id. It uses a specific verb ('Delete') and resource ('contract/license'), and distinguishes from sibling tools like add_company_agreement and update_company_agreement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., deactivating via update_company_agreement). It implies usage for removal but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses the verb 'Remove', which aligns with the 'destructiveHint: true' annotation. However, it does not disclose additional side effects (e.g., whether the ticket remains, permissions needed) beyond what the annotation already conveys. The annotation carries the transparency burden adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence. While it avoids fluff, it sacrifices necessary detail for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and zero parameter documentation, the description is insufficient for an agent to use the tool correctly without guessing parameter meanings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the three required parameters (ticket, company, project). An agent cannot infer what values to provide without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove a ticket link') and the resource ('CRM company'), distinguishing it from the inverse sibling tool 'link_customer_ticket'. However, there is slight inconsistency between the title ('customer') and description ('company'), which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as the sibling 'link_customer_ticket' or other linking tools. There are no prerequisites or context about required prior state (e.g., ticket must be linked).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety profile; description adds that slug is derived and de-duplicated, and returns the new record. However, it doesn't disclose whether the operation is idempotent, potential side effects, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise at three short sentences, front-loading the main action. No filler, but could be more structured to improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description lacks completeness. It doesn't explain optional parameters, expected response format beyond 'returns the new company record', or error conditions. Insufficient for a tool with 4 parameters and no schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It only explains 'project' (implicitly) and 'name' (slug derivation), but omits 'notes' and 'domain' entirely. Two of four parameters remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a company in the project's CRM, with slug derivation and deduplication. It distinguishes from sibling add_* tools by targeting companies, but doesn't explicitly differentiate from add_contact or add_lead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like add_contact or add_lead. The description only implies usage for creating companies, but does not specify prerequisites or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds 're-render the page without it', providing some context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no wasted words. Action is front-loaded and the meaning is immediately understood.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with one parameter and no output schema, the description lacks explanation of what 'passcode gate' means, what 're-render' entails, and parameter semantics. It feels incomplete for an AI agent needing to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain the 'project' parameter at all. It only implies the target site but gives no details on format, values, or how it's used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it turns off the passcode gate and re-renders the page. The verb 'turn off' and resource 'passcode gate' are specific, distinguishing it from its sibling 'enable_login_gate' despite no explicit comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like enable_login_gate. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only. The description adds context about the work log source and the pricing config override, which is useful. However, it doesn't disclose error behavior, data freshness, or any limits, so only moderate additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with front-loaded purpose and a parenthetical for important config detail. No wasted words, though the list of metrics could be slightly streamlined. Efficient but dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists what the snapshot contains (counts, completions, velocity details). However, missing parameter explanation and lack of structural detail (e.g., JSON keys) leave gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameter. It does not describe what 'project' is or any constraints. The only indirect reference is 'project config' in a note about pricing, which is insufficient for an agent to know how to populate the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a read-only snapshot of feature/bug counts by status, completions by date, and velocity metrics. The verb and resource are implied but specific. However, it doesn't differentiate from siblings like get_work_log or get_sprint_report, which might overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this over alternatives. Does not mention when not to use it, prerequisites, or context like needing a project ID. The only hint is the config override note, but that's about behavior, not usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds significant behavioral context: returns defaults if not built, and explains the unmanaged block scenario. This goes beyond the annotation, though it omits error handling or auth details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action but includes a ticket reference (FBMCPB-64) that is not useful for an agent. The second sentence on edge cases is necessary but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description does not fully describe the return structure. It lists some fields but not the shape or defaults. Also, the parameter is not explained, and the tool's behavior under error conditions is omitted. Given the tool's simplicity, it remains somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must explain the 'project' parameter. It mentions 'the resolved site directory (websiteLocation, else <project>/site/)' but does not explicitly define the parameter's meaning or format. This is insufficient for an AI agent to understand what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the project's splash/website config and lists the fields it retrieves. It distinguishes itself from write tools like set_site, though it does not explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool vs alternatives. It only states what it does, without prerequisites, exclusions, or context for when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's mention of deletion is redundant. The added value is the constraint that the home page cannot be removed, which is a behavioral trait. No other traits (e.g., permissions, irreversibility) are disclosed. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two short sentences with no extraneous words. It is front-loaded with the action. However, it could benefit from including brief param guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no parameter descriptions, and a simple action, the description fails to provide enough context. It doesn't explain the result (e.g., what happens to dependent files), required permissions, or how to undo. The exception about home page is helpful but insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 2 required parameters (slug, project) with zero description coverage. The description only mentions 'by slug' but does not explain what slug or project mean, nor their format or constraints. It adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'sub-page (by slug) and its rendered file', matching the title. It also notes the exception for the home page, but doesn't differentiate from sibling deletion tools like remove_test_page or remove_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only mentions that the home page cannot be removed this way, which implies an alternative exists but does not name it. No prerequisites or context of use are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly, non-destructive, idempotent. Description adds no further behavioral details such as error handling, duplicate behavior, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (one sentence) and front-loaded, but could include parameter details without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two string params and no output schema, the description provides adequate purpose context but lacks parameter semantics and behavioral details, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description fails to explain what 'name' and 'project' represent, leaving the agent without semantic guidance for parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb 'Add' and resource 'product to a board's product list', and provides usage context for tagging tickets. It clearly distinguishes from siblings like remove_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies when to use (for tagging tickets) but does not explicitly contrast with alternatives or state when not to use. No exclusion guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, implying a safe read operation. The description adds context that it lists assets from a specific folder, but does not disclose additional behavioral details like pagination or sorting. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the action and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description fails to explain the 'project' parameter, which is critical for invocation. Additionally, it lacks information about any filtering or organization of assets beyond what is listed. Incomplete for a tool with one required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'project' is not explained in the description. With 0% schema description coverage, the description should clarify what 'project' refers to (e.g., project ID or name), but it does not. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists assets under the site's assets/ folder and specifies the returned fields (name, ref, size). It is distinct from sibling tools like upload_site_asset and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as upload_site_asset or other list tools. The description does not specify prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds 'permanently remove,' which is consistent. However, it does not disclose potential side effects, such as whether the task is deleted entirely or just unlinked from the board, or if the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. However, it is too terse and could benefit from added context without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two required parameters with no schema descriptions and no output schema, the description is insufficient. It omits crucial details about parameter usage and the delete operation's outcome, leaving the agent with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters (ticket and project), and the description does not explain what these parameters represent. The agent lacks clarity on how to identify the task (e.g., is ticket an ID?) or the project context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (permanently remove), resource (task), and scope (from its board). It distinguishes the tool from siblings, as no other sibling tool targets task deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives or when not to use it. The description does not mention prerequisites, consequences, or related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only; description adds value by specifying included data fields, but lacks details on potential issues like response size or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads the core concept ('Full campaign') and is free of extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description gives a sense of what is included, it omits parameter explanations and does not fully describe the return structure, especially given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters 'id' and 'project', leaving them ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a full campaign including recipients, open stats, and send-batch sizes, distinguishing it from sibling tools like list_campaigns which likely provide a summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_campaigns, nor any prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds minimal context by specifying that the attachment is a 'previously attached file path or URL', but does not disclose additional behavioral traits beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no verbosity, but it could be structured better with separate lines for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention return values, error cases, or side effects (e.g., what happens if the attachment does not exist). The context is incomplete for a removal tool with 3 required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate. It partially explains the 'attachment' parameter as 'file path or URL', but leaves 'project' and 'ticket' unexplained, relying on agent inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Detach' and identifies the resource as 'file path or URL from a ticket', clearly distinguishing it from sibling tools like 'add_attachment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it specify any prerequisites or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already indicates destructiveHint=true, so the description's 'Remove' is consistent but adds no extra behavioral context (e.g., cascading effects, permanence). Without annotations, this would be a 1; with annotations, it provides minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous words, front-loaded with the verb and resource. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive action with no output schema, the description covers the basic operation. However, it lacks details on consequences (e.g., what happens to associated data) and prerequisites, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters described). The description reinforces the contact id format with an example, but adds little beyond the schema. Baseline 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the resource (contact), the context (from a company), and the identifier (contact id with example). It effectively distinguishes from sibling tools like add_contact and update_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or avoid, no prerequisites or alternatives mentioned. The description only states what it does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no hints (all false), so the description carries full burden. It discloses the side effect of re-rendering index.html and the partial update behavior, but does not address auth needs, error handling, or whether the project must exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences front-load the purpose and then add side effect and constraint. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though the description covers the main fields and side effect, it lacks details on return values (no output schema), error cases, and the structure of nested objects (seo subfields are undocumented). Adequate for simple use but incomplete for complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (seo described). The description adds meaning for title, tagline, theme, and sections, but does not mention the 'project' (required) or 'seo' parameters. This partially compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the splash site (title, tagline, theme, sections) and re-renders site/index.html. It distinguishes from siblings like get_site (read) and deploy_site (deployment) but 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Only provided fields change,' implying partial updates, but provides no guidance on when to use this tool versus alternatives like scaffold_site, apply_site_template, or set_site_analytics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds the partial update behavior ('Only provided fields change'), which is useful but does not disclose side effects, permission requirements, or other behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain the response format, required parameters (project, ticket), or confirmation behavior. For a tool with 15 parameters, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 53% (8 of 15 parameters have descriptions). The description does not add any parameter-level information; it merely states that fields are updated, leaving the agent to rely on the incomplete schema for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'task', and specifies partial update behavior 'Only provided fields change', distinguishing it from sibling tools like delete_task or get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like set_status or set_handoff, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (all false), so the description carries most of the burden. It reveals it is a write operation and stores under a specific path, but lacks details on permissions, idempotency, or behavior on overwrite. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and location, then usage guidance. No redundant words or information. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention return value, success/failure signals, or preconditions (e.g., project existence). With 4 parameters and some undocumented, the description is incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, meaning two parameters lack descriptions. The tool description adds overall context (base64, utf8, path) but does not elaborate on each parameter individually (e.g., project, encoding). It fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Save'), the resource ('reference/source image'), and the purpose ('to use as input for media generation'). It distinguishes from the gallery ('kept separate from the gallery') and explains usage in prompts. This fully differentiates from sibling tools like save_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (before generation) and mentions keeping separate, but does not explicitly state when not to use or provide alternatives. Siblings like save_media exist but are not compared. Usage context is clear but no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false so the description carries burden. It notes contact ids are unique within company, which is useful. However, lacks details on side effects, permissions, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, precise sentences with no waste. Front-loads the primary purpose and adds a key constraint (unique id).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing important context: no return value description (no output schema), no explanation of the required 'project' parameter, no error conditions (e.g., duplicate id behavior). For a creation tool, more guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (17%); description lists fields (name, email, role, phone) but provides no syntax or validation rules. Does not explain 'project' parameter which is required. Adds moderate value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the verb (add), resource (contact), and specifies fields (name, email, role, phone) and target (company). Differentiates from siblings like update_contact or remove_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Implicitly for creating a new contact, but no exclusions or context about prerequisites or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds some behavioral context beyond annotations: it indicates the tool is a mutation (adds a feature) and returns a ticket ID. However, it does not disclose side effects, authorization needs, or what happens to existing data. Annotations are all false, so the description partially compensates but not fully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that immediately convey the core action and return value. Every word is purposeful, and there is no superfluous or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 12 parameters and no output schema, the description is minimal. It does not explain what a 'feature' is, how the board is identified, or what mandatory parameters (like project and title) are required. The agent lacks enough context to use the tool confidently without additional schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 58% schema description coverage, the schema provides meanings for some parameters (e.g., ref, dueDate, newFile). The description adds no additional parameter information beyond what the schema already provides. The baseline for moderate coverage is 3, and the description does not improve upon it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a feature') and the specific resource ('to a board's featurelist.md'). It also mentions the return value (new ticket ID), making the tool's purpose unmistakable. This distinguishes it from similar tools like add_features_bulk or commit_feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as add_features_bulk or commit_feature. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations leave behavioral hints ambiguous (readOnlyHint=false, etc.), but the description adds context: drafts are stamped for review, not legal advice, and optional save writes to media gallery. This goes beyond the 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded main action. Efficient, but could benefit from structured sections (e.g., parameters, behavior).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose, optional features, and draft disclaimer. Missing details on output format (though 'return draft markdown' is stated), error handling, permissions, and required fields. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%. The description adds meaning for 'company' (auto-fills customer_name) and 'save' (writes to media gallery), but does not explain 'template' enum values, 'project', or 'vars' beyond what the schema provides. Insufficient compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: fill a standard contract template with given fields and return a draft markdown. It mentions optional auto-fill from CRM and saving to media gallery, but does not explicitly differentiate from sibling tools like add_company_agreement or list_contract_templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides some context (auto-fill from CRM, save option, drafts for review) but lacks explicit guidance on when to use this tool versus alternatives, such as updating an existing agreement or listing templates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true; description adds details about returned data (counts, pipeline value) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are sufficient and front-loaded with key information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes output but omits parameter explanation. For a simple tool, this is acceptable but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage for 'project' parameter, and description does not explain it. Agent cannot determine what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides geographic and pipeline rollup for leads map, distinct from listing leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs siblings like list_leads or other map-related tools. Mentions rendering is left to board, but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (readOnlyHint, etc.), so the description carries the burden of behavioral disclosure. It adds 'Does not actually send — tracking only,' clarifying the tool's non-destructive, non-sending nature. However, it does not detail side effects or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with zero wasted words. Every sentence adds value: the first states the action and effect, the second clarifies a key limitation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema, no nested objects), the description covers the core function and limitation. However, the complete lack of parameter documentation leaves a gap. It is minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters (id, project) with no description coverage (0%). The tool description provides no explanation of what id or project represent, leaving the agent to infer meaning solely from the tool name and context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Record that a draft was sent'), specifies the resource (draft email), and differentiates from actual sending by noting 'Does not actually send — tracking only.' This distinguishes it from sibling tools like draft_email and list_mail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (after a draft is sent, to record the event) and what it does not do (does not send), but does not explicitly state when not to use or name alternative tools. Guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's mention of 'returns matching assets' is consistent and adds little beyond that. The description does not disclose additional behavioral traits like rate limits, authentication needs, or result limits, but it does not contradict 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose. It is concise and to the point, with no wasted words. However, slightly more structure (e.g., listing parameters explicitly) could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description vaguely mentions 'returns matching assets with metadata' but provides no details on pagination, limits, or error behavior. For a search tool, this leaves some gaps, but the overall functionality is communicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context beyond the schema by explaining how parameters are used ('by kind, by exact tag, and/or a free-text query'), but the project parameter is only implied via 'a project's media gallery'. With 0% schema description coverage, the description partially compensates but omits details like parameter formats or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search/filter a project's media gallery by kind, by exact tag, and/or a free-text query... Returns matching assets with metadata.' It specifies the resource (media gallery) and the operations (search/filter), but does not explicitly differentiate from sibling tools like 'list_media'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching/filtering media but provides no explicit guidance on when to use this tool vs alternatives like 'list_media' or 'get_media'. There is no mention of when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: derivation logic (cap label, median, default) and output fields (basis, confidence, spend so far, suggested model). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main purpose. It is slightly verbose with technical details but remains clear and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The algorithm is well explained and output fields are listed, but there are gaps: the relationship between 'project' param and 'all open tickets' is ambiguous; no output structure; no error conditions or prerequisites described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation for the 'project' parameter (e.g., format, meaning). The description must compensate but fails to add any semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides per-ticket token estimates for all open tickets using historical data. The verb 'estimate' and resource 'work' are specific, and it distinguishes from sibling tools like plan_work or log_work.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the algorithm but does not explicitly state when to use this tool versus alternatives. It implies usage for obtaining token estimates, but lacks guidance on when not to use or what alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is known to be read-only. The description adds no behavioral details beyond 'full', which is useful but not essential given 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the core action, and contains no fluff, though it could benefit from a structured list of parameters or return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and no output schema. The description states it returns the 'full email message', but does not specify what fields are included or error conditions, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description only explains 'id' implicitly ('by id') and does not clarify the role of the 'project' parameter, leaving its semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a full email message by id, specifying the verb ('get') and the resource ('email message'), and distinguishes it from list_mail by noting the id comes from there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from list_mail' implies the tool should be used after listing emails to get full details, but it does not explicitly state when to use or not use it, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: true and openWorldHint: false. The description adds value by listing the breakdown components, but does not explain behavioral aspects like data freshness, caching, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the purpose and output structure. It could be slightly improved by front-loading the verb, but overall it is clear and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the key output elements. However, it lacks parameter documentation and usage context, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not elaborate on the single parameter 'project' beyond its name and type. No format hints, allowed values, or relationship to other concepts are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a composite 0-100 health score with grade and breakdown covering specific dimensions (bug pressure, feature progress, momentum, freshness). It distinguishes the tool as a dedicated health-check resource among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking project health but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds detail on returned fields, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no fluff, directly conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with one required param and no output schema, but the description omits explanation of the 'project' parameter, leaving a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'project' (required) is not mentioned in the description. Schema coverage is 0%, so description must explain it but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List the defined geographic lead areas' and specifies returned fields (id, name, centre, radius). Distinct from siblings like add_lead_area.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives, but the tool's list function is straightforward and implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, consistent with listing. Description adds output structure details (slug, title, file) and home page mention, but no further behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that front-loads the tool's action and includes specific output structure. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description adequately explains what is returned. Lacks parameter explanation, but overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the 'project' parameter. Without context, an agent cannot know what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists site pages, including the home page and sub-pages with slug, title, and file. It distinguishes from sibling tools like add_page or remove_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, but the purpose is straightforward. Siblings like add_page imply creation vs listing, so usage context is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds that the tool lists images under a specific path and that they serve as inputs for generation, providing minor behavioral context beyond annotations. No mention of pagination, sorting, or access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 14 words, zero waste. Essential information front-loaded. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (one parameter, no output schema, annotations present), the description omits many contextual details: what fields the list returns, ordering, filtering capabilities, or any confirmation of the operation's effect. The agent lacks sufficient information to fully understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter (project). The description does not explain the parameter's purpose, format, or relationship to the listed images. For a low-coverage schema, the description should compensate but fails to add any parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists reference/source images under media/uploads/ and notes they are inputs for generation. It specifies the verb (list) and resource (reference images) distinctly, distinguishing it from sibling tools like list_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like list_media or search_media. The description implies usage for viewing generation inputs, but does not provide when-not-to-use or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior. The description adds that a new ticket is created and returned, which is consistent. However, it does not disclose side effects, required permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the action and return value. No extraneous information; every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 12 parameters and no output schema, the description only covers the basic operation. It does not explain how parameters like 'priority' or 'labels' affect behavior, nor does it describe the structure of the returned ticket beyond the ID.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 58% (7 of 12 parameters have descriptions). The tool description adds no additional parameter guidance. It misses the opportunity to clarify key parameters like 'title' or 'project', which are required but lack descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Log a bug'), target ('board's buglist.md'), and return value ('new ticket (FBB-###)'). It distinguishes itself from siblings like 'add_feature' or 'create_project' by focusing on bug tracking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for logging bugs but does not specify when to use this tool versus alternatives like 'add_feature' or 'create_project'. No explicit when-not-to-use or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's mention of 'Remove' is consistent. It adds value by noting the return value (remaining count), but does not disclose other behavioral traits like irreversibility or required permissions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a brief return note. It is concise, front-loaded, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 3 required parameters, no output schema, and no param descriptions, the description is inadequate. It does not explain the purpose of 'name' and 'project', nor does it specify behaviors like error handling or idempotency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only hints that 'id' is the annotation ID (from get_media), but does not explain the 'name' and 'project' parameters. With 0% schema description coverage, the description fails to compensate, leaving these parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the resource (annotation from an asset), and how to specify it (by id from get_media). It effectively distinguishes from sibling tools like remove_media_comment or remove_attachment by focusing on annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the id should come from get_media, but does not explicitly state when to use this tool versus alternatives like remove_attachment or remove_media_comment. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show no special hints (readOnly false, etc.). Description adds that it creates a bug and links/records, but does not disclose side effects (e.g., notifications, idempotency, permissions needed). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. No fluff; every word adds value. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 parameters, no output schema, and no return value description. Covers core action but omits what is returned (e.g., bug ID). Missing behavioral context and usage prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description does not explain parameters beyond schema. Schema has 25% coverage (only 'company' described). No added meaning for 'title', 'project', or 'description'. Fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it logs a company-reported bug, creates a board bug (FBB-###), links to company, and records report. Distinguishes from siblings like 'log_bug' and 'resolve_company_bug' by specifying the company context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage from description (company-reported bugs) but no explicit guidance on when to use vs. 'log_bug' or when not to use. Lacks alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable detail beyond annotations: explicit deduping logic (whitespace normalization, duplicate dropping), output file naming convention, and reiteration of read-only behavior. This helps the agent understand side effects and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first covers the core process and deduping, second highlights read-only nature and output. Efficient and front-loaded, with no extraneous information. A brief example output path would improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main inputs, processing (deduping), and outputs (file names). Lacks error handling, prerequisites (e.g., ticket existence), or volume limits. For a tool with no output schema, the description provides sufficient context for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), but the description explains the ticket parameter's role in file naming and the variants parameter's composition (model+content). The project parameter lacks explanation. The description partially compensates for the low coverage but leaves project unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explains the tool ingests test variants, dedupes, and returns file contents for writing. The verb 'Ingest... returns' clarifies it does not actually save to disk, distinguishing it from sibling save tools. However, the title 'Save generated test variants' may mislead an agent into thinking it writes files directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like generate_test or generate_multi_model_tests. The description assumes the agent already knows it should call this after generating variants, but does not specify prerequisites or contrasting scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context: re-renders the site and how to remove analytics via enabled:false. This well complements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose, parameters, and behavior. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and siblings, the description omits the required 'project' parameter and lacks usage guidance. It covers key behavioral aspects but is not fully complete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (40%). The description explains most parameters (id, provider, snippet, enabled) but fails to mention the required 'project' parameter. It adds meaning beyond schema but not for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an analytics snippet to every page's <head>, with options for Plausible, GA, or custom. However, it does not differentiate from sibling tools like 'set_analytics_config' or 'auto_configure_analytics', which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or mention that 'auto_configure_analytics' might be a better choice for automatic configuration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries full burden. It mentions that the tool 'persists' ideas and 'returns created tickets', indicating it is a write operation with a return value. However, it lacks details about potential destructive behavior, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) and front-loaded with the core purpose. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (array of objects with multiple properties) and lack of output schema, the description is adequate but incomplete. It mentions the return value ('Returns the created tickets') but does not explain how failures are handled, nor does it contrast with related tools like 'commit_feature' or 'add_feature'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but fails to do so. It does not explain any of the parameters (e.g., 'project', 'features', or nested fields like 'title', 'labels', etc.). The description only mentions 'features' indirectly in the context of brainstorming, providing no additional meaning over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds several features at once, using the verb 'add' and specifying 'several features' as the resource. It distinguishes itself from the sibling tool 'add_feature' by emphasizing bulk operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool ('after brainstorming: you generate the ideas, this persists them'). It implies a specific workflow but does not explicitly state when not to use it or suggest alternatives like the singular 'add_feature'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds that the tool upserts by ticket and derives verdicts automatically unless overridden. However, it does not disclose potential side effects, permission requirements, or error handling for write operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with key information front-loaded. No unnecessary words, but could be slightly more structured (e.g., bullet points for parameters).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the recording action and optional inputs but lacks guidance on how this tool fits with sibling tools (drift_report, drift_remediate) and does not describe return behavior or error states. Adequate for a straightforward tool but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning for the gap and files parameters beyond the schema by describing their purpose. With 57% schema coverage, the description partially compensates but does not cover the semantics of ticket, project, or verdict parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool records a fidelity score for a single ticket in a drift run, with explicit verb and resource. Distinguishes from siblings like drift_start and drift_report by focusing on per-ticket scoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context (within a drift run, per ticket) and mentions upsert behavior, but does not explicitly state when to use this tool vs alternatives like drift_report or drift_remediate. No exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond what annotations already provide (readOnlyHint=true). It adds the filtering behavior, but does not mention side effects, permissions, or the return format. The description is consistent with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. It front-loads the purpose and scoping in the first sentence and adds a practical tip in the second. No redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of annotations, the description covers the main purpose and parameter usage. However, it lacks information about the output format, pagination, or potential limits, which would be helpful for a complete understanding. The absence of an output schema increases the need for such details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for two of the three parameters (ticket and includeResolved) beyond the schema definitions. It clarifies the scoping to a ticket and the filtering behavior for resolved comments. The schema has 67% coverage, so the description compensates by providing usage hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists review comments for a project, optionally scoped to one ticket, and mentions the resolved state. It uses a specific verb and resource, which helps distinguish it from many sibling tools, though it does not explicitly differentiate from similar list tools like list_media_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage tip about setting includeResolved:false to see only open feedback, which guides the agent on how to filter. However, it offers no guidance on when to use this tool versus alternatives, such as list_media_comments or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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. It adds the ordering and filter context but no additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every element (verb, resource, order, optional filters) is concisely presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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, the description is mostly complete but lacks explanation of the required 'project' parameter. Absence of output schema is acceptable for a list tool, but parameter coverage could be better.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by mentioning 'asset' and 'platform' as filters, but it fails to explain the required 'project' parameter. This is a gap for one of three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'saved share drafts', ordering 'newest-first', and optional filters. It is specific and distinguishes from sibling tools like 'draft_share' and 'remove_share'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing share drafts) and mentions optional filters, but it does not explicitly provide when-to-use vs alternatives or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive, so the description adds value by detailing asset type handling and return value. However, it lacks disclosure on idempotency, side effects of duplicate publishing, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the core purpose, and each sentence adds meaningful behavioral context. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and minimal annotations, the description covers asset type behavior and return value but misses failure modes, parameter details (especially required 'project'), and differentiation from siblings like 'add_page'. Could be more complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with 'name' and 'slug' having descriptions; 'title' and 'project' lack descriptions. The description does not compensate for the missing parameter descriptions or add detail beyond the schema, e.g., no clarification of what 'project' refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and the resource 'gallery asset as a page on the project site'. It explains behavior for different asset types and distinguishes from siblings like 'add_page' and 'upload_site_asset'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but provides no guidance on when to use it versus alternatives like 'add_page' or 'deploy_site'. No exclusions or when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true, so the description's 'Delete' is consistent. However, no additional behavioral traits are disclosed (e.g., irreversibility, cascading effects, or confirmation needed). With annotations covering the destructive nature, the description adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous words. It efficiently conveys the core action and required identifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description provides minimal context. It lacks details on error handling, safety nets (e.g., confirmation), or what happens to associated data. Given the tool's simplicity, it is adequate but leaves the agent with unanswered questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'by name', clarifying the 'name' parameter but ignoring 'project'. Without explaining the project identifier, the agent cannot determine how to delete a test page uniquely. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The name, title, and description all consistently state the tool deletes a test page. The verb 'delete' is specific, and the resource 'test page' is clear. It distinguishes from siblings like 'save_test_page' and 'list_test_pages' by indicating the removal operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a test page needs to be deleted by name, but it lacks explicit guidance on when to use this tool versus alternatives (e.g., removing a page via another tool) or any prerequisites like required permissions or existence of the page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=true. The description adds that the decision and timestamp are recorded, which provides context beyond annotations but does not disclose potential side effects or permissions required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-changing tool with no output schema, the description covers the main action but lacks details such as prerequisites (message must exist and be pending) or post-effects (e.g., status change). It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with zero description coverage. The tool description does not explain the parameters, relying solely on their names and the enum values for 'decision'. This is insufficient for an agent to understand usage specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (approve or reject) and the resource (pending CRM inbox message), and specifies that it records the decision and timestamp. This differentiates it from sibling tools like 'add_crm_message' or 'list_crm_inbox'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reviewing pending messages but does not provide explicit guidance on when to use this tool versus alternatives, such as when a message should be approved or rejected, or what the prerequisites are.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, and the description adds context about the target folder ('test-pages/'). However, it does not disclose potential side effects of overwriting or required permissions, which are partially covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It conveys the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with good annotations, the description is adequate but missing details on what happens if the page already exists (overwrite behavior) and whether the operation is reversible. Given no output schema, return value is unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%, only name has a description), and the description does not elaborate on the parameters beyond stating the folder path. The meaning of 'project' and 'html' is not clarified beyond the schema's basic type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create/overwrite a standalone HTML test/QA page', providing a specific verb and resource, and distinguishes from sibling tools like get_test_page and remove_test_page by implying write vs read/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for saving test pages but does not explicitly state when to use this tool over alternatives like get_test_page or list_test_pages. No guidance on when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotence and non-destructiveness. The description adds no further behavioral details such as permission requirements, error handling, or side effects beyond the basic update functionality. It does not contradict 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and includes examples. While very concise, it could be better structured (e.g., bullet points) for readability, but it avoids unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema, the description should at least mention required fields (project, company, id) and return value. It does not discuss what the tool returns upon success or failure, leaving gaps for an AI agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13% (only the 'id' parameter is described). The description lists example fields ('expiresAt', 'status', 'seats', 'term', 'value') but does not provide detailed semantics, formats, or allowed values for any parameter, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Update a company contract/license by id') and provides concrete examples such as extending a license or changing status, seats, term, or value. This differentiates it from sibling tools like add_company_agreement and remove_company_agreement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing agreements but does not explicitly state when to use this tool versus alternatives like add_company_agreement or remove_company_agreement. No exclusion criteria or context-based guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, etc.). Description adds that it creates a new record and returns it, but doesn't detail side effects, permissions, or duplicates. Neither contradicts annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with all key information front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters and no output schema, description covers basic purpose and main parameters but omits 'project' and doesn't detail return structure or required fields beyond kind. Some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description lists most parameters but misses 'project'. Adds some context (e.g., kind enum, template source) but schema coverage is low (18%) and descriptions for many parameters are just names. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Record' and resource 'contract or license on a CRM company'. Differentiates from siblings like 'update_company_agreement' and 'remove_company_agreement'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes what it does but lacks explicit guidance on when to use vs alternatives. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains idempotent behavior (calling with same title updates in place), avoids destructive overwrites (numeric suffix for slug collisions), and reveals an automatic side effect (keyword-matching into work packets). These details add value beyond the annotations (idempotentHint=true, destructiveHint=false), providing practical behavioral context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding crucial information: the primary action, the update behavior and slug handling, and the side effect. No extraneous words, well front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with three parameters and no output schema, the description covers input expectations (title, content, project context), behavior on repeated calls, naming conventions, and automatic integration. It does not mention the return value or how to confirm success, but the idempotentHint and real-world usage patterns reduce the need for that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies how the 'title' parameter maps to a filename via slugification and explains the update logic for same-title calls. The 'content' parameter is clearly described as markdown body. The 'project' parameter is implied through 'board's kb/ folder' but not explicitly defined. Given schema description coverage of 67%, the description compensates with meaningful additional context beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (write a markdown doc into kb/ folder) and the resource (markdown doc in board's kb/). The title 'Add/update a kb doc' reinforces the dual behavior. However, it does not explicitly distinguish this tool from sibling tools like list_kb_docs, get_kb_doc, or search_kb, relying on the verb 'write' to imply it is a create/update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. While the description implies it is for adding or updating knowledge base documents, it does not mention scenarios where one might prefer search_kb or get_kb_doc instead. The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutating) and destructiveHint=false, which aligns with 'append'. The description adds detail about timestamping and building history, but does not disclose potential side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and includes essential details (kind options, timestamp) without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but lacks details on return behavior, optional parameter defaults (e.g., 'at' defaults to now), and parameter format expectations (e.g., id like 'L3'). Given the absence of output schema, more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 40% (only 2 of 5 parameters have descriptions). The description explains 'kind' with enum values and mentions 'note', but does not clarify 'project', 'id', or 'at'. It partially compensates for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (append a touchpoint) and the resource (lead's interaction log). It distinguishes from siblings like add_lead, enrich_lead, and convert_lead by focusing on interactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for logging interactions but does not explicitly state when to use this tool versus alternatives like add_crm_message or add_contact. No exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it uses heuristics similar to validate_feedback, labels the request as ask:<source>, and records the requester. Annotations are minimal (no readOnly, etc.), so the description adds some behavioral context but does not fully explain side effects or creation process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loading the action and important characteristics. However, the second sentence could be integrated more smoothly, and the structure is adequate but not exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain what the tool returns after structuring a request (e.g., ticket ID, confirmation). Given the complexity of creating a ticket, this is a significant gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, and the description adds meaningful context: 'source' becomes part of the label, and 'from' is recorded in the description header. This goes beyond the schema descriptions for those parameters, though 'project' remains unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool structures pasted external requests into features or bugs using heuristics, specifying input types (Slack message, email) and output labeling (ask:<source>). It distinguishes itself from a live intake listener.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'paste-to-structure, not a live intake listener,' which gives some usage context. However, it does not explicitly state when to use this tool over alternatives like validate_feedback or other intake tools, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true. The description adds context ('per-project notes surface shared with Claude') but does not disclose additional behavioral traits beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and context, second states return format. No redundant words. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers purpose, resource, and return type. Missing parameter clarification, but overall adequate given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description does not explain the 'project' parameter format (e.g., ID or name), only refers to 'a board's freeform scratchpad.md'. Minimal added value for parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'board's freeform scratchpad.md', and the content 'raw markdown'. It distinguishes from siblings like set_scratchpad and append_scratchpad by emphasizing read-only retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies reading use but does not explicitly state when to use this tool versus alternatives like set_scratchpad or append_scratchpad. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that events are captured automatically by specific tools, that the timeline merges two data sources, and that it tolerates tickets with no recorded events (pre-FBMCPF-142). This is rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the main purpose. It avoids unnecessary words while including key details like the types of events and the edge case for older tickets. Minor improvement could be to separate the two data sources more clearly, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and moderate complexity, the description covers the main purpose and an edge case (tickets with no events). However, it does not describe the output structure (e.g., whether results are ordered, what fields are returned) which would help an agent understand what to expect. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. However, it only mentions 'one ticket' and 'project' implicitly; it does not explain the format, constraints, or relationship between the two required parameters. For a 2-parameter tool with no schema descriptions, the description adds minimal parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a 'Full audit timeline for one ticket' and specifies the types of events (status moves, priority moves, etc.) merged with work-log entries. It distinguishes this tool from siblings by mentioning it combines field-change events and work logs, which is unique among related tools like get_ticket_diff or get_timeline_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for getting the combined history of a single ticket, but it does not explicitly state when to use it over alternatives (e.g., get_ticket_diff for diffs, get_timeline_data for timeline). No exclusions or conditions are given, so the guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds the ordering behavior (newest-first). However, it does not disclose response structure, pagination, or any limitations, which would be helpful for a list tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys all essential information without any wasted words. It is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, no output schema, and the presence of readOnly annotations, the description provides sufficient context for basic usage. It could be improved by mentioning the required project parameter and response format, but it is largely complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions filtering by status and company but does not mention the required 'project' parameter, leaving ambiguity about its role. The description partially covers parameter semantics but misses crucial information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (list), resource (leads), ordering (newest-first), and optional filters (status and company). It distinguishes from other lead-related sibling tools like add_lead, set_lead_status, and leads_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (to list leads with optional filters) but does not explicitly exclude alternatives or mention when not to use it (e.g., for mapping use leads_map). The context is adequate but lacks direct sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no readOnly or destructive hints. The description discloses it writes to test_runs.md, which is a mutation, but does not detail whether it appends or overwrites, nor mention permissions or side effects. Some transparency exists but insufficient for a full behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. Every sentence adds value: the first states what it does and the parameters, the second clarifies its role vs test execution. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description lacks details about the required 'project', return value, and behavior on duplicates. It covers the core functionality but misses contextual details that would help an agent fully understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 14% (suite described). The description clarifies that passed, failed, skipped are integers for counts and ticket/summary are optional strings, adding meaning beyond the schema. However, it does not explain the required 'project' parameter, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it records test run results (passed/failed/skipped) to the board's test_runs.md, distinguishing it from sibling tools like get_test_runs (read) and generate_test (create). The verb 'Record' and resource 'test run result' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after running tests ('You run the tests... this stores the report') but does not explicitly state when to use it versus alternatives like get_test_runs or log_bug. No guidance on exclusions or prerequisites is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions 'pending review' and auto-subject synthesis, providing some behavioral context beyond the all-false annotations. However, it does not disclose return value, side effects (e.g., notifications), or whether it creates or updates records, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences front-loaded with purpose and key details. Every part adds value with no redundancy. Efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description is largely complete. It explains input fields and behavioral traits (pending review, subject synthesis). Minor gap: no indication of return value or confirmation, but adequate for an intake action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds semantic context for most parameters: it explains the category enum in plain language, notes optional company, and mentions auto-generation of subject. Schema coverage is 57%, but description compensates by highlighting key fields, though 'project' is not addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Capture' and resource 'support or contact submission' into the CRM inbox. It specifies the action (submission intake) and distinguishes from siblings like add_crm_message by mentioning 'pending review'. However, it does not explicitly differentiate from all related CRM tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the context as 'inbound support or contact submission', implying when to use. But no explicit when-not-to-use or alternatives (e.g., add_crm_message). The usage is adequately implied but lacks clear guidance on exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true) already indicate the tool performs a read operation. The description reinforces this with 'reverse lookup' and does not add significant new behavioral details beyond the relationship direction. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the tool's purpose in few words, though it could be slightly expanded to include parameter guidance without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a lookup tool with 2 simple parameters and no output schema, the description adequately explains the function. However, it lacks details on the output format (list of companies) and any potential limitations like pagination. The absence of parameter descriptions also reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. However, the description provides no details about the 'project' and 'ticket' parameters, such as format, example values, or constraints. The parameter names are self-explanatory, but the description misses an opportunity to add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a reverse lookup to find CRM companies linked to a board ticket. It uses specific verbs ('surfaces') and resource ('ticket↔customer relationship'), distinguishing it from sibling tools like list_companies or get_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Reverse lookup' implies the tool is used when you have a ticket and need to find related customers. It doesn't explicitly state when not to use it or mention alternatives like link_customer_ticket, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, confirming a write operation. The description adds that the message starts pending review, but no details on side effects or authorization beyond what is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic purpose and use case but omits lifecycle details like what happens after pending review or any prerequisites beyond the required project parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters; with 50% schema coverage, the description should compensate but does not, leaving undocumented parameters like body, from, subject without context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'add an incoming message to the CRM inbox' and specifies that it starts pending review, distinguishing it from sibling tools like review_crm_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for logging inbound emails/leads needing triage and approval, providing clear context but not explicitly excluding other tools like submit_crm_intake.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals behavioral traits beyond annotations: a default status 'new' with a pipeline flow, and optional fields ('value', 'lat/lng') that affect the pipeline and leads map. Annotations only indicate non-read-only and non-destructive, so this adds meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose and key defaults, with no extraneous information. Every sentence provides value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no output schema), the description covers the essential creation logic and default behavior but omits details like return value, error handling, or duplicate prevention. It is adequate for a simple CRUD tool but incomplete for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 10% schema description coverage, the description compensates partially by explaining 'name' (implied required), 'value', and 'lat/lng' usage. However, it fails to describe 7 out of 10 parameters (city, email, source, company, status, etc.), leaving significant gaps for an AI agent to understand proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a sales lead'), the target store ('project's leads store (crm/leads.json)'), and distinguishes from siblings like 'list_leads' or 'enrich_lead' by focusing on creation. The mention of default status and pipeline context adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for initial lead creation by mentioning default status 'new' and pipeline stages, but it lacks explicit guidance on when to use it versus alternatives like 'enrich_lead' or 'convert_lead'. No exclusion criteria or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, idempotentHint=false) indicate mutation, but the description adds return info: 'Returns the new annotation (with a stable id) and the total count.' 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose and return behavior. No unnecessary words, clear and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 50% schema coverage, no output schema, and few annotations, the description explains the return value but fails to describe key parameters like 'project', 'name', and 'author'. The term 'pin-based' could be elaborated. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (3 of 6 parameters described). The description restates x/y coordinates but adds no new meaning. Required parameters 'project' and 'name' are not described, and 'author' is also missing. The description does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a pin-based comment/annotation') and the resource ('to an asset'). It distinguishes from sibling tools like add_media_comment by specifying 'pin-based' and optional coordinates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pinning annotations on assets but does not explicitly state when to use this tool versus alternatives like add_media_comment or remove_annotation. No when-not or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by specifying that existing notes are preserved and that ticket ID mentions surface in work packets. However, it does not disclose potential side effects like file size limits, error conditions, or whether the file is created if missing. With annotations already marking it as non-destructive and a write operation, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the core action and effect. Every sentence adds value: the first defines the operation, the second adds a useful linking feature. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple append tool with no output schema, the description covers the primary action and the ticket-linking feature. However, it lacks details about error handling (e.g., invalid project, missing scratchpad), formatting behavior, and whether the append is atomic. It is minimally adequate but has noticeable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes 'text' as 'Text to append' and does not describe 'project'. The description does not provide additional meaning for either parameter: it does not clarify what 'project' represents (e.g., ID or name) or imply any constraints beyond the schema. The ticket ID mention is a usage tip, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('append'), the resource ('board's scratchpad.md'), and the effect ('preserving existing notes'). It also introduces the unique feature of linking to ticket IDs, distinguishing it from siblings like set_scratchpad (overwrite) and get_scratchpad (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 notes without overwriting) and provides a specific usage hint about ticket IDs. However, it does not explicitly state when not to use it or mention alternatives (e.g., set_scratchpad for overwriting), leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond annotations by describing validation (company exists, contact belongs) and storage behavior (crm/bookings.json, status 'scheduled'). Annotations are non-contradicting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, then validation, then storage details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Good coverage given complexity: explains workflow, validation, and storage. Missing return value info, but acceptable since output schema not provided. Sufficient for a booking tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Explains 'company' and 'contact' validation relationship and 'at' as ISO timestamp. Schema coverage is 50% but description partially compensates. Other parameters (type, notes, subject, durationMins, project) are not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it schedules calls/demos/meetings with a CRM company and optional contact. It distinguishes from siblings like list_bookings and cancel_booking, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides when to use (scheduling) and mentions validation steps, but lacks explicit when-not-to-use or alternative tools. Context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that recipients are validated and deduplicated, and that voiceLint conditionally scores body copy as a warn-only attachment. Annotations (readOnlyHint=false) are consistent. No destructive behavior is mentioned, but the tool creates a resource, so behavioral transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences covering main action, recipient processing, and a conditional feature. It is front-loaded with the core purpose. No unnecessary words, but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description mentions returns: campaign + stats. However, it lacks details on stats content, error conditions, or constraints like duplicate names. Given the tool's complexity (6 params, 3 required), it is minimally complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 33% with descriptions only for batchSize and recipients. The description adds context about recipient validation and batch size computation, but does not explain required parameters like project and name. For a 6-param tool, the description adds marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a marketing campaign with recipient list and batch size. It specifies recipients are validated and deduplicated, and that sending is handled separately. It also mentions a conditional voiceLint feature. This distinguishes it from sibling tools like list_campaigns and get_campaign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for campaign setup, leaving sending to user/connector. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions. There is no direct comparison with other campaign-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint false, etc.) are present and not contradicted. The description adds that it creates files and returns a ticket prefix, but lacks detail on side effects or permissions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, directly front-loaded with the primary purpose. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with 2 parameters and no output schema, the description explains what is created and hints at the return value. Missing details about ticket prefix derivation, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context: 'name' is also the folder name, and 'description' is stored atop featurelist.md. This goes beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new board folder with specific files (featurelist.md and buglist.md) and returns a ticket prefix. It distinguishes from siblings like add_feature or create_campaign by focusing on project-level creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or compare to similar tools like add_features or set_project_config.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces 'Read-only' while adding detailed behavioral context: the flat-file nature, supported formats, and specific data contents for each 'what' option (e.g., 'date, ticket, model, tokens, additions/deletions'). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three clauses in two sentences. It front-loads the primary purpose and efficiently covers variants, formats, and safety. The 'mirroring export_tasks' phrase adds slight ambiguity but doesn't waste space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple flat-file export tool with 3 parameters and no output schema, the description covers the essential: purpose, what data is returned for each 'what' value, supported formats, and read-only nature. It doesn't fully specify output structure (e.g., field order in CSV), but given the context, it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears full burden. It explains the 'what' parameter's two enum values in detail (including output fields) and mentions 'formats: json or csv'. The 'project' parameter is not elaborated, but its purpose is obvious. Overall, it adds significant value beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Flat-file export of analytics for external BI/spreadsheet use' and specifies two variants (worklog and completions) with concrete output fields. It also mentions mirroring export_tasks, but the distinction is implied rather than explicit, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by naming export_tasks as a sibling, suggesting it's an alternative for analytics data, but does not explicitly state when to use this tool versus others or provide exclusions. The two 'what' options offer some guidance, but no clear 'when-not-to-use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds value by detailing the merging behavior (MCP config over legacy project_config.json). No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and merge behavior but lacks details on return format, error cases, or permissions. Given the simple read-only nature, it is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only implies the project parameter without providing format, examples, or additional meaning. Minimal value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a board's settings and lists specific fields (products, code location, etc.). It also explains the merging behavior, distinguishing it from sibling tools like set_project_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading config, but does not explicitly state when to use it versus alternatives like get_board or get_global_config. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds that the output is HTML, providing extra context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description is minimal. It lacks explanation of the 'project' parameter's role and does not describe return format details or error cases. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description mentions 'by name' clarifying the 'name' parameter, but does not explain the 'project' parameter (e.g., project ID or name). Missing critical semantic information for one of two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Read' (synonymous with get) and specifies 'one test page's HTML by name', clearly identifying the action and resource. It distinguishes from siblings like list_test_pages (listing) and remove_test_page (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like list_test_pages or get_test_runs. The description only states the basic functionality without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint=true, confirming safe read-only behavior. The description adds context about the summary content but does not disclose additional behavioral traits like pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core purpose and then details the summary. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with annotations and few parameters, but the description omits clarification on how 'limit' affects the returned list and does not explain the relationship between the list and summary. With no output schema, the description could do more to fully inform the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, the description does not mention the 'limit' or 'project' parameters at all, leaving the agent to infer their meaning from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Read), the resource (recorded test runs), ordering (most-recent first), and the return value (summary with total runs, latest result, passing status). This distinguishes it from other test-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reviewing recent test runs and overall health. However, it does not explicitly mention when to use this over alternatives like 'test_runs_by_suite' or 'get_regressions', leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it confirms a read-only listing operation, specifies ordering (newest-first), and details the included stats (recipients, opens, open rate, batch count). No contradiction with readOnlyHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose and key details (ordering, stats). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should cover return details more fully. It mentions stats but omits pagination, result structure, or whether all campaigns are returned. Adequate for a simple list tool but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters (project, status). It only mentions 'marketing campaigns' without clarifying how project or status affect the results, leaving the agent to infer parameter meaning from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists marketing campaigns with newest-first ordering and includes summary statistics (recipients, opens, open rate, batch count). It effectively distinguishes from sibling tools like get_campaign (single campaign) and create_campaign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a filtered list of campaigns with stats but does not explicitly state when to use or avoid this tool versus alternatives like get_campaign for a single campaign or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), the description discloses that vendor/build directories are skipped, depth controls expansion, and tool is sandboxed to codeLocation. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences covering purpose, skipped directories, and constraints. Front-loaded with the main action. Slightly more structure or formatting could improve readability, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, constraints, and sandboxing, but does not detail the return format (e.g., structure of file list, whether it's recursive, or error handling). Given no output schema, more detail would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds context that subpath is optional and depth controls expansion, but the schema already describes these. The 'project' parameter lacks description in schema and the tool description does not clarify what constitutes a project ID or name, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists files and folders under codeLocation with details like sizes and extensions. The verb 'list' and resource 'code files' are specific. Among many siblings, this tool is distinct for listing code files, contrasting with read_code_file or code_file_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for browsing the codebase structure, but it does not explicitly state when to use vs alternatives or when not to use. No exclusions or context for selecting this tool over similar ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint annotation by stating it returns an empty gallery if no media folder exists. It does not cover potential rate limits or auth details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded but becomes verbose by listing asset attributes (kind, mimeType, etc.), which could be more appropriate for an output schema. Some redundancy reduces conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains basic listing and empty gallery behavior but omits pagination, sorting, or limits. For a simple list operation, it is adequate but has gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (project param lacks description). The description does not clarify the project parameter's format or constraints, and restates the kind filter already in schema. Little added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a project's media gallery with images and reports, specifying verb, resource, and scope. It distinguishes from siblings like get_media or search_media by focusing on the entire gallery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the read-only nature and optional kind filter, guiding usage. However, it does not explicitly compare with alternatives like search_media or explain when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds value by detailing the return format (flat and threaded), which is beyond what annotations convey. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words. Efficiently conveys purpose and output format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but return format is partially described. Parameter context is missing (e.g., valid values, how to construct identifiers). Annotations provide readOnlyHint but no error or prerequisite info. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions. The description mentions 'asset' but does not clarify how 'project' and 'name' identify the asset. For a tool with no schema descriptions, the description should add parameter meaning; it fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'asset's comments', and the output format (flat array and threaded tree). It distinguishes from siblings like add_media_comment (create) and remove_media_comment (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., list_review_comments). Usage is implied as a list operation, but no when/not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds little beyond stating the list is under a configured folder. No details on pagination, sorting, or return format are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no extraneous information. Front-loaded verb and scope. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, good annotations, and no output schema, the description is mostly complete. However, it does not specify what information is returned (e.g., board IDs, names). Minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% trivially. The description notes the list is 'under the configured boards folder', which adds context beyond the schema. Baseline 4 for zero parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'List all' and identifies the resource as 'boards (projects)' with a clear scope 'under the configured boards folder'. It distinctly separates from sibling tools like 'get_board' (single) and 'create_project' (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Usage is implied by the name and description, but there is no mention of alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to repeat safety. The description adds no extra behavioral detail, but the tool is simple and the annotations suffice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words, conveying the essential action and location.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations, the description is nearly complete but lacks clarification of the 'project' parameter, which is a key input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'project' has no description in schema (0% coverage) and the tool description does not explain its meaning. The agent may not know what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'standalone HTML test pages under test-pages/', distinguishing it from siblings like 'get_test_page' (individual page) and 'remove_test_page' (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool or when to use alternatives (e.g., get_test_page). The context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it appends data and feeds velocity and health metrics. Annotations show it is not read-only, not idempotent, and not explicitly destructive, which aligns with the append action. It adds context beyond annotations, though it could be more explicit about potential side effects on existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is dense and front-loaded with the core action. It efficiently conveys the purpose, but could benefit from clearer separation of details (e.g., using a second sentence).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description provides essential context (board work log, tied to ticket, feeds metrics). However, it does not explain the return value or what happens after logging, such as confirmation or log entry ID. The parameter list is not fully covered, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names several parameters: summary, tokens, additions, deletions, model, ticket. However, it misses required parameter 'project' and optional parameters 'inputTokens' and 'outputTokens'. This partial coverage adds some meaning but is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Append a work event to the board's work log' and specifies the content: summary, tokens, additions/deletions, model, tied to a ticket. This distinguishes it from sibling tools like log_heartbeat or record_dispatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its purpose (logging work events) but does not explicitly state when to use it over alternatives or provide conditions for usage. Context from siblings suggests it is the appropriate tool for logging work events, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, so description's 'Delete' aligns. Beyond annotations, it adds the source of ids (list_shares), but no extra details on side effects, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the action and most critical information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, description covers core action and id source but fails to explain the required 'project' parameter. Missing output schema means return behavior is not described, but this is acceptable for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description only mentions 'id' parameter but does not explain 'project' parameter, leaving its role unclear. This is a significant gap given lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Name and title clearly indicate the action (remove/delete) and resource (share draft). Description explicitly states 'Delete a share draft by its id' and references source from list_shares, making action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage context by stating 'from list_shares' to obtain the id. No explicit when-to-use or alternatives, but sibling tools show no other share removal, so guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds concrete behavioral details: the exact state changes (setting board bug to Done, flipping report entry to resolved). This goes beyond annotations, though it omits potential side effects or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb ('resolve'), front-loading the action and outcome. No extraneous words; every part contributes to purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about return values (no output schema) and prerequisites (e.g., whether the bug must be in a specific state). Given the complexity of the task (two side effects), more context would help ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 67% (ticket and company have descriptions, project does not). The tool description does not add any parameter meaning beyond the schema; it does not clarify the project field or provide format examples. The description fails to compensate for the missing schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (mark a bug resolved) and the specific changes: sets board bug to Done and flips company report entry. This distinguishes it from sibling tools like 'log_bug' (logging new bugs) and 'report_company_bug' (reporting, not resolving).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for resolving company-reported bugs but does not explicitly state when to use this tool versus alternatives (e.g., when to use 'log_bug' or 'company_priority_tickets'). No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints (readOnly=false, destructive=false). Description adds useful context: updates only sidecar, tags deduplicated, returns new tag list. This compensates for annotation silence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and key behavioral detail (sidecar-only update), no redundant words. Every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 params, no output schema, no param descriptions. Description covers core behavior but lacks parameter specifics and examples. Adequate for a simple tagging tool but could be more complete given low schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no property descriptions. The description mentions 'add and/or remove tags' which aligns with 'add' and 'remove' parameters, but does not explain 'name' or 'project' (both required). No format or constraints for tag strings are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Add and/or remove' and specific resource 'custom tags on a media asset'. It distinguishes from siblings by noting it only updates the sidecar, not bytes or version history, which is unique among media tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for adding/removing tags but does not explicitly guide when to use vs. alternatives like annotate_media (structured annotations) or edit_media. No 'when not to use' or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes storing asset and returning ref. Missing behavior on overwrites, size limits. Annotations (destructiveHint=false) not contradicted, but description adds limited behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous text. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return value. Lacks error handling and overwrite behavior, but sufficient for typical use. Good given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 50%; description adds context for encoding (base64/utf8) and name constraints, but project parameter remains unexplained. Adds some value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Store' and resource 'asset under site's assets/ folder'. Differentiates from sibling list_site_assets which lists, not uploads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: upload assets. Mentions name must be plain filename with extension, but lacks guidance on when to use this vs alternatives like upload_reference, and no prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds context that the tool derives settings from existing tracking and errors if none exist, which are important behavioral traits. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and front-loaded, containing the core purpose and key constraints. However, it lacks parameter explanation, though this is partly compensated by the brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, no output schema, and good annotations, the description covers the main purpose and error condition. However, missing parameter documentation and lack of explicit usage context (e.g., when to use vs. set_analytics_config) leave some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required parameter 'project' with no description (0% schema coverage). The description does not explain what 'project' is or its format, leaving the agent to guess. Since the description fails to add any meaning beyond the schema, this dimension scores low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Derive the external analytics read config from the site's existing tracking settings' and mentions enabling the proxy. It distinguishes the tool from siblings like 'set_analytics_config' by automating configuration based on existing settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: to avoid retyping the domain/property. It also states an error condition when no analytics are configured, implying it should not be used in that case. However, it does not explicitly name alternative tools such as 'set_analytics_config' for manual configuration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by specifying the ticket split into features/bugs, priority ranking, and reporting of missing linked IDs, which are not disclosed by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds important behavioral detail. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 2 parameters and no output schema, the description adequately explains the output structure (sorted list with missing IDs). Minor gap: no mention of pagination or limits, but overall sufficient for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (company described, project not). The description does not explain the 'project' parameter or add meaning beyond the schema. Given low coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a company's linked board tickets, split into features and bugs, ranked by priority, and reports missing linked IDs. This verb+resource combination is specific and distinguishes it from siblings like list_companies or list_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving priority-ranked tickets but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusions, making it adequate but not proactive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and scope are covered. The description adds that it includes an overall rollup and untested tickets per product, giving output context but no behavioral traits like rate limits or error handling. With annotations, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, and wastes no words. Every sentence adds value: the first explains the aggregation, the second lists output components.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the purpose and output shape (overall rollup, untested tickets). It does not mention any filters like date range or status, but given the tool's likely use case and annotations, this is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter 'project' (string) with no description in the input schema (0% coverage). The description mentions 'per product' but does not clarify that 'project' likely refers to a product identifier, nor does it specify valid values or format. The agent must infer meaning, which increases ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool rolls up per product the count of tickets with and without recorded test runs, making testing gaps visible. It specifies the resource (tickets per product) and the action (roll up), distinguishing it from sibling tools like get_test_runs or test_runs_by_suite which focus on individual test runs or suites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool is for making testing gaps visible on the board, providing clear context for its use. However, it does not explicitly state when not to use it or mention alternative tools for more detailed test run analysis, missing a chance to guide agents away from misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only (mutates), non-destructive, non-idempotent. The description adds context: validates recipients, optionally links to CRM, and voiceLint behavior (scores body and attaches 'voice' as warn-only). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first covers main purpose and key limitation, second adds optional CRM, third details voiceLint. Well-structured and front-loaded. The third sentence is slightly lengthy but still clear. Minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not mention return value (e.g., draft ID) or how to reference the draft later. It also does not explain 'project mail center' context. Given moderate complexity (6 params) and sibling tools like 'list_mail', 'get_email', some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'to' and 'company' described). The description mentions recipients are validated and CRM tie-in, but does not explain 'project', 'cc', 'subject', 'body' formats or constraints. For a tool with 6 parameters, this is insufficient additional guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool composes and saves an email draft, emphasizing it does not send. It specifies the resource ('email draft in the project mail center') and action ('compose and save'), and distinguishes from sending via explicit note. This matches 'draft_email' well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'does not send—there is no mail connector; the user or a future connector sends', making it clear when to use (drafting) and when not (sending). It also mentions optional CRM tie-in. However, it does not name sibling tools like 'mark_email_sent' explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, covering safety. The description adds detailed behavioral context: it computes tokens, cost, additions/deletions, days, rework, medians, totals, matched pairs. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core purpose and systematically lists all returned metrics. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description adequately explains all returned components and input conventions. It lacks edge-case handling (e.g., empty results) but is sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'project' has 0% schema description coverage and the tool description does not explicitly describe it. Although inferable from context, the description should clarify what project string is expected, especially given no output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares board-workflow vs chat-workflow trials using specific label conventions. It lists exact returned metrics, distinguishing it from siblings like get_sprint_report or drift_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when comparing the two workflows with labeled trials, but does not explicitly state when not to use or mention alternatives. Context is clear but lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the readOnlyHint by stating it lists templates. It adds the specific templates included, but does not elaborate on behavior beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded, with concrete examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully explains what the tool returns (standard templates with fields), which is sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivial. The description does not need to add parameter semantics, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists standard contract templates (NDA, MSA, SOW, commercial license) with required fields, distinguishing it from sibling tools like generate_contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool. The description does not mention when to prefer it over alternatives like generate_contract.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by specifying the ordering ('newest-first') and filter options. No contradictions found; the description discloses behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently front-loads the tool's purpose and then lists optional filters. No wasted words; appropriate length for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 parameters and no output schema, the description covers ordering and filters but lacks details on pagination, return format, and the required 'project' parameter. Could be more complete given the absence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions type, status, and company parameters along with possible values, but omits the required 'project' parameter and does not explain the 'company' parameter format. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'CRM inbox messages', and adds ordering 'newest-first' and optional filters. This distinguishes it from sibling tools like list_leads or list_companies, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., list_leads). The resource name is self-explanatory but the description lacks explicit when/why-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's assertion of listing is consistent. It adds context about the nature of variations (alternatives from one prompt) beyond annotations, but does not disclose details like pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but could be more structured (e.g., bullet points). Adequately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations, the description is sufficient but lacks details about the output (e.g., what properties are returned). No output schema, but description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It hints that 'group' is a variation group ID and 'project' is needed, but does not explain format or constraints. Some added meaning, but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists gallery assets sharing a variation group ID, with specific context (alternatives from one prompt) and use case (side-by-side review). It uses specific verb 'list' and distinct resource, differentiating from siblings like 'list_test_variants'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reviewing variations side-by-side, but does not explicitly state when not to use or provide alternative tools. Still, the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it specifies that existing ticket tags are unaffected, which is not evident from 'destructiveHint: true'. No contradiction with annotations. The side-effect clarification is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It conveys the essential purpose and a critical side-effect concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with no output schema and few parameters, the description adequately covers the core behavior and side-effects. However, it does not address potential edge cases (e.g., what if the product doesn't exist). This is acceptable given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%; the tool description provides no explanation of the two parameters (name, project). The description does not compensate for the missing schema descriptions, leaving the agent to infer parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the resource (a product from a board's product list), and includes a clarifying note about side effects (ticket tags left as-is). This distinguishes it from siblings like add_product and remove_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (removing a product while preserving tags) but provides no explicit guidance on when to use versus alternatives (e.g., not removing, or using a different tool). No exclusions or when-not context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: states no secrets are stored, push uses machine's git credentials, and gitMode controls commit_feature/deploy_site behavior. This aligns with idempotentHint and destructiveHint=false, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the main purpose. It is concise but could separate the gitMode explanation for clarity. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 params, no output schema, annotations present), the description covers purpose, relationship to other tools, and key behavior. However, it omits details on several parameters and does not describe return values or error conditions, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (29%: 2 of 7 params have descriptions). The description adds meaning for gitMode (enum values explained) and push (back-compat, superseded), but other params (branch, remote, enabled, messagePrefix) remain undocumented. Insufficient compensation for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it enables/configures per-project git integration, specifying the action (enable/configure) and resource (git integration). It distinguishes from sibling tools like set_global_config and get_git_config by mentioning per-project override.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (to enable git integration per-project) and mentions prerequisites (setting codeLocation). It contrasts with set_global_config by stating gitMode overrides account-wide default for this project. It does not explicitly list when not to use, but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true, and the description confirms overwriting. No additional behavioral traits are disclosed beyond what the annotations provide, such as return values or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with 3 parameters and no output schema, the description covers the key aspects: purpose, behavior (overwriting), and downstream effects. Minor gaps exist (e.g., error handling), but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%) with only the 'note' parameter having a description. The tool description adds context for 'note' (free-form markdown) but does not clarify 'ticket' or 'project' parameters, leaving ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Write a ticket's handoff note), the resource (handoff note for a ticket), and the format (free-form markdown). It also specifies the file path (handoffs/<TICKET>.md), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use (for successor ticket info) and an alternative to retrieve the note (get_work_packet). However, it does not explicitly state when not to use this tool or mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and side effects. The description reinforces that it does NOT save, which aligns with annotations. However, it adds no further behavioral details beyond what annotations provide, so the addition is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficiently conveying purpose, scope, and next steps. It front-loads the main action and adds critical context. Slight improvement could be made by clarifying the parameter, but overall it is well-structured and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 param, no output schema, annotations present), the description covers purpose, usage flow, and safety. However, the lack of parameter explanation leaves a gap. An incomplete parameter description limits completeness for a tool that relies on the only input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter 'project' with no description (0% coverage). The description mentions 'from the project's config, brand, and products' but does not clarify what 'project' means (e.g., name, ID, or path). The agent may be uncertain how to specify the project, making this a significant gap despite the tool's simplicity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to derive a draft of .mcpb packaging metadata from project config, brand, and products. It explicitly says it does NOT save and distinguishes itself from the sibling tool save_packaging_config. The verb 'suggest' and resource 'packaging metadata' are specific and unique among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool to generate a draft, then refine it, and finally persist with save_packaging_config. It clearly indicates when to use this tool and when to use the alternative, leaving no ambiguity about the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds context about storage format ('[Attachments: ...] on the ticket line') and restates idempotency. It discloses the effect without contradicting annotations. Additional traits like authorization or side effects are not covered but the tool is simple.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical clarification, no redundancy, and all information is front-loaded. Every word adds meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (attaching to a ticket), the description adequately covers the action, idempotency, and storage format. No output schema exists, so return value is not explained, but it's implied success. Minor gap: no mention of required permissions or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%) with only the 'attachment' parameter described as 'A file path or URL.' The description reinforces this but does not elaborate on 'project' or 'ticket'. It adds marginal value beyond the schema for one parameter, but fails to compensate for the other two underscripted parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Attach' and resource 'to a ticket', specifying that it attaches a file path or URL. It distinguishes itself from siblings like remove_attachment by focusing on adding, and includes idempotency detail. The resource and action are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding attachments to tickets but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though sibling remove_attachment exists. Preconditions (e.g., ticket existence) are not discussed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly, non-destructive behavior. The description adds context that the defined area is used by leads_map to tag leads and roll up counts/value, which is beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding value: first defines the tool's action, second explains the integration with leads_map. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple definition tool with 5 required parameters and no output schema, the description covers the main functionality and downstream use. However, it lacks explanation of the 'project' parameter and does not specify coordinate format or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the purpose of most parameters (name, lat, lng, radiusKm) but does not mention the 'project' parameter. Schema coverage is only 20%, so the description partially compensates but misses important context for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Define' and the resource 'circular geographic area' with specific attributes (name, centre lat/lng, radius km). It also explains the downstream effect on leads_map, distinguishing it from sibling tools like update_lead_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when defining lead areas for the leads map, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent, non-destructive writes. The description adds behavioral context: it replaces any existing sprint label and allows clearing with null. This goes beyond annotations but does not disclose potential errors, rate limits, or exact response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and includes the key special case. Every word adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 params and no output schema, the description covers core functionality and the null case. However, it lacks details on response, error handling, and atomicity for multiple tickets. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (sprint has a description matching null usage). The tool description does not clarify what 'project' refers to (ID? name?) or the format of 'tickets' (array of ticket IDs). The implied meaning from context is insufficient given the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move one or more tickets into a sprint'), specifies the mechanism (sets sprint:<name> label, replacing existing), and includes the special case of null to send tickets back to backlog. This distinguishes it from related sibling tools like create_sprint or update_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use (assigning tickets to a sprint) and the null case for backlog. However, it does not explicitly state when not to use this tool or mention alternative tools (e.g., set_status for single ticket updates).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The disclosure of idempotency adds value beyond annotations. The description is consistent with annotations (idempotentHint=true, destructiveHint=false). It could mention other behaviors like notifications or refunds, but the existing context is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences to convey core purpose and idempotency. No extraneous words exist; every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and idempotency, it fails to explain the 'project' parameter. Given three parameters and no output schema, the description should be more thorough to fully guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%). The description only clarifies 'id' and 'reason' but omits any explanation of the 'project' parameter, which is required. This leaves a significant gap in understanding the tool's input requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (cancel), the resource (booking), and specifies the id comes from list_bookings. It effectively distinguishes from sibling tools by being specific to booking cancellation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool (with a booking id from list_bookings) and mentions idempotency. However, it does not explicitly state when not to use it or provide alternatives, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that 'Hand-added sections are preserved' and clarifies default behavior ('done defaults to true'). This provides useful behavioral context not captured in structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three short sentences that front-load the action. Every sentence adds value: the first states the primary action, the second mentions preservation behavior, and the third clarifies a default.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool with no output schema, the description covers the main action, default, and an important preservation detail. It could mention error cases or return value, but overall it is fairly complete given the tool's simplicity and the existing schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage, the description adds meaning for 'index' (1-based) and 'done' (defaults to true). However, it does not explain the 'ticket' and 'project' parameters, which are required. The description partially compensates but does not fully cover the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Toggle the checkbox') and the resource ('acceptance criterion on a ticket's requirements pad'). It clearly distinguishes from sibling tools like 'set_requirements' and 'get_requirements' by focusing on a single toggle operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the toggle action and noting that 'done defaults to true', but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear enough for a simple operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces this by describing data aggregation without mutation. It adds behavioral context: lists worst-first flagged tickets with gaps, pending unscored tickets, and the Wilson interval for sampling. Contradictions: none.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with purpose, and includes all essential information without redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters and no output schema, the description adequately explains what the tool returns (scores, intervals, flagged/pending tickets). It is complete enough for an agent to understand the tool's output, though it omits details like output format (e.g., JSON structure).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds that runId defaults to the latest run, which matches the schema's description. However, it does not provide additional meaning for the required 'project' parameter beyond its name. Schema coverage is 50%, and the description compensates somewhat by explaining the report's scope but not the parameters' formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Aggregate') and lists concrete outputs (per-ticket scores, mean fidelity, verdict counts, drift rate, Wilson confidence interval, flagged tickets). It clearly distinguishes from sibling drift tools (drift_start, drift_record, drift_remediate) by focusing on aggregation and reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after a drift run ('Aggregate a drift run') but does not explicitly state when to use versus alternatives (e.g., drift_record for raw records). No exclusion criteria or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context about live editing and re-rendering beyond annotations (readOnlyHint=false). But does not disclose handling of invalid indices, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with 'Live editor', efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main functionality well, but misses edge cases (invalid index, project requirement) and does not explain return values (no output schema). Adequate for a simple edit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only index has schema description (25% coverage). Description explains index role and that heading/body are patchable, but does not clarify 'project' parameter format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (patch/append), resource (website section), and distinguishes between updating existing by index and appending new. Among many edit tools, this is specific to site sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides when to use index vs omit, but lacks explicit comparison to alternatives like set_site or add_page. Implicit differentiation is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds value by clarifying the gate is client-side and passcode ships in the page, which goes beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences with a critical note. Every sentence adds value: first states purpose, second provides behavioral nuance. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core functionality and the nature of the gate, but does not describe return values or what happens after enabling. The 'project' parameter is not elaborated. With no output schema, more detail on results would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2/3 parameters described). The description only adds that a passcode is required, mirroring the schema. It does not explain the 'message' parameter or provide additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Turn on' and resource 'passcode gate for the project's hosted site'. It distinguishes the tool from its sibling 'disable_login_gate' by using 'enable' vs 'disable' in the name and the description's action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: it's a soft client-side gate, not real authentication, and mentions the requirement of a passcode. It implicitly advises against using it for real auth, but does not explicitly list when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds return behavior ('Returns null-ish when no such source exists') beyond the readOnlyHint annotation. It does not contradict annotations. However, it could disclose potential errors or output size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states purpose and input, the second explains a critical behavior (null return). Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with 2 required params and no output schema, the description explains what it returns (raw text + citation fields) and null behavior. Minor gap: no specification of output format or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'slug (or title — it gets slugified)' which adds meaning to the slug parameter beyond the schema. However, the project parameter is completely undocumented in the description, and schema coverage is only 50%, so the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one source's full raw text + citation fields', specifying the verb (Read), resource (source), and scope (by slug or title). It distinguishes from siblings like list_sources and add_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (by slug or title) but does not explicitly state when to choose this tool over siblings such as search_kb or list_sources. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the agent knows it's a read operation. The description adds 'full details' but no further behavioral traits. With annotations, the bar is lower; this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence of 14 words, no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with no output schema, the description covers the essential purpose and usage. It could mention what 'full details' includes or error handling, but given simplicity, it's nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only illustrates the ticket parameter with an example (FBF-12), but does not clarify the project parameter. Thus partial but insufficient coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full details of a single task', with an example ticket ID format. It distinguishes itself from sibling tools like list_tasks (list) and update_task (modify).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing full details of a single task. It does not explicitly mention when not to use or list alternatives, but the sibling context (e.g., list_tasks, update_task) makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. Description adds 'De-duplicated' and storage location, which are useful behavioral traits beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no redundant words. Efficiently conveys purpose and key behavioral notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool with 3 required params and no output schema, the description sufficiently explains purpose and effect (customer portal). Lacks return value hints, but idempotentHint compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters with descriptions. The description does not add new parameter-level info beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb and resource: 'Link a board ticket to a CRM company'. Distinguishes from siblings like unlink_customer_ticket and ticket_customers by specifying the effect (shows in customer_portal) and de-duplication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context (customer portal visibility) but lacks explicit when-to-use or when-not-to-use compared to alternatives. No mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, indicating a safe read operation. The description adds value by specifying the ordering (newest-first) and clarifying the relationship between sent items and mail history. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, ordering, and filtering options. No wasted words; front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (one required) and no output schema. The description explains two optional filters but omits the required project parameter and does not describe the output format. For a simple list tool, basic completeness is achieved but gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters (status, company, project) with 0% description coverage. The description only mentions status and company as optional filters, but fails to explain the required project parameter, which is a significant gap. Since schema provides no descriptions, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (mail), ordering (newest-first), and optional filters (status, company). It distinguishes itself from siblings like 'get_email' by specifying it's a list operation, and the mention of 'Sent items form the mail history' adds specific context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (listing mail with optional filters) and mentions that sent items form the mail history. However, it does not explicitly state when not to use it or suggest alternatives, leaving some room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark as read-only; description adds valuable context about the return data (progress per sprint, backlog count) without any contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loading the purpose and key output details without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully specifies the return structure (progress per sprint with fields and backlog count), making it complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single parameter 'project'. The description does not explain what 'project' refers to (e.g., project ID or key), failing to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List a board's sprints' with detailed output including progress metrics and backlog count, clearly distinguishing it from sibling tools like get_sprint_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing sprints with progress but provides no explicit guidance on when to use this tool versus alternatives like get_sprint_report or create_sprint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds value by stating it 'updates open-rate stats,' which is a behavioral trait beyond annotations. However, it could disclose more about permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence (21 words) that front-loads the core action. Every word is meaningful, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 required string params, no output schema), the description covers purpose, idempotency, and side effects. However, the complete lack of parameter documentation is a notable gap, especially with zero schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain the three parameters (project, id, email) beyond their names. It neither maps them to campaign ID or recipient email nor provides any format hints. The description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records that a recipient opened a campaign, using a specific verb and resource. It distinguishes itself from sibling tools like create_campaign or get_campaign by focusing on recording an open event with idempotency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the tool is for use 'when a mail connector or manual entry reports opens,' providing clear context. It does not specify alternatives or when not to use, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. The description adds context by explaining the idempotent behavior and the impact on work packets and queues, which is valuable beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded key information (action and id format), no redundant words. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, idempotent, non-destructive), the description covers the outcome adequately. No output schema exists, but the description explains the effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the id parameter format ('RC-<n>'), adding value over the schema. However, the project parameter is not described, and schema coverage is only 50%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action is to 'resolve' a 'review comment' by its id (RC-<n>). The verb and resource are specific and unambiguous, differentiating it from other tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the effect of resolving all comments (stops surfacing, leaves next_task queue) but does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds the behavioral detail that it records the update time, which is valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The purpose is front-loaded, and every sentence adds value. Appropriate for a simple status update tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with no output schema, the description covers the key behavior (status transition and time logging). It doesn't mention return values or state constraints, but the annotations provide safety profile, making this adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It enumerates the valid status values but does not explain the 'id' or 'project' parameters beyond what the schema provides. The description partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('move a lead along the pipeline') and lists the exact allowed statuses ('new/contacted/qualified/won/lost'). It clearly distinguishes from sibling tools like convert_lead or enrich_lead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when updating lead status but gives no explicit guidance on when to use this tool versus alternatives. No exclusions or context for deciding between sibling tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable behavioral details: 'Re-renders the page' and 'Merges over existing SEO' (rather than replacing). This clarifies that the tool modifies the system and is safe to repeat. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the key purpose and scope. The second sentence adds two important behavioral notes. No redundant information, but the second sentence could be more cohesive. Overall efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description covers the main functionality and merge behavior. However, it omits potential side effects of re-rendering (e.g., performance impact), required permissions, and the response format. For a mutation tool, these details would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (43%), so the description must compensate. It explains slug usage (omit/'index' for home), image path format, and ogType values. It also maps 'description' to meta description and implies ogTitle and ogDescription. However, it does not describe the 'project' parameter or provide full syntax for all fields, leaving gaps that the schema does not fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets SEO metadata for a page, distinguishing between the home page (via omitting slug or using 'index') and sub-pages. It lists specific fields (meta description, Open Graph tags, image) and mentions merge behavior, making the purpose unambiguous and distinct from sibling tools like set_site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: for home page vs sub-page via slug. It implies usage for SEO metadata updates but does not explicitly state when not to use it or suggest alternatives like set_site for site-wide settings. The guidance is adequate but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (destructiveHint=true, idempotentHint=true) by stating 'Overwrite' and 'replace existing content'. It adds useful context about the specific file and board beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences, front-loading the core purpose and providing a helpful alternative reference without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema), the description covers the main action adequately. However, missing parameter semantics for 'project' creates a gap. Overall, it is minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 50% of parameters with descriptions; the description does not compensate for the undocumented 'project' parameter. It fails to explain what 'project' refers to, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Overwrite'), the resource ('a board's scratchpad.md'), and distinguishes from the sibling tool 'append_scratchpad' by specifying the alternative for adding without replacing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use 'append_scratchpad' instead, providing clear context for choosing between tools. However, it does not specify when not to use this tool beyond that alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only; description adds that it surfaces coverage/health and lists failing suites, providing useful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded with the main action, though slightly dense with detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple aggregation tool with one parameter and no output schema, the description provides adequate context about what is returned, though parameter documentation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'project' with no schema description (0% coverage). The description does not explain the parameter's purpose or that it is a required filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it organizes test runs by suite with aggregated metrics like latest result, count, pass/fail, and pass-rate, distinguishing it from a flat list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies use for suite-level aggregation instead of a flat list, but lacks explicit when-not-to-use or comparison with siblings like 'get_test_runs'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden. It discloses the side effect 'Re-renders all pages so theme/gate stay consistent,' which is a key behavioral trait. However, it doesn't clarify if the operation is destructive or idempotent, but the 'update' implication and lack of destructive hint suggest non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey purpose, output, and a notable side effect. It is front-loaded and free of unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description lacks details about return values, error conditions, prerequisites (e.g., project existence), and conflict handling. The side effect is mentioned, but overall completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 40%, the description adds minimal value: it mentions 'title and sections' but does not clarify 'project' or 'seo' beyond what's in the schema. The baseline is 3 due to coverage, and the description does not significantly enhance understanding of parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds or updates a sub-page of the project site, specifying the output path (site/<slug>.html) and distinguishing from set_site for the home page. It is specific and unique among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says not to use for home page (managed by set_site), implying use cases for sub-pages. It could be improved by mentioning alternative tools like set_page_seo for SEO-only updates, but the current guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe read). The description adds behavioral details: recursive mapping, regex-based symbol extraction (with capping), and that results are ordered 'worst first' for split candidates. It doesn't mention performance implications or recursion depth limits, but it sufficiently 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each packed with valuable information. The first sentence covers the core mapping functionality and outputs, the second details the optional symbols feature. No unnecessary words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description gives a good high-level overview but lacks specifics like the cap value for symbols, performance implications, or the exact structure of the returned data. While 'worst first' clarifies ordering, more detail on output format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%) with only 'symbols' having a description. The description compensates by explaining the role of splitBytes and splitLines ('split thresholds (lines/bytes)') and that symbols:true triggers per-file symbol lists. However, the 'project' parameter is only implicitly defined as 'the project's codeLocation', lacking precise meaning. This provides some added value but not full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool recursively maps the codebase, reports total file count and bytes, counts by extension, and identifies files exceeding split thresholds as candidates. It also explains the optional symbol extraction. This distinguishes it from siblings like list_code_files (which likely lists files) or suggest_file_split (which suggests specific splits).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the usefulness: 'for spotting oversized modules to decompose' and 'a lightweight symbol map for navigation.' While it doesn't explicitly name alternatives or state when not to use, the context of siblings like list_code_files and read_code_file is implied. It provides clear usage guidance without being exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that editing saves a new version and archives the prior copy, which is critical behavioral info beyond annotations. Annotations already indicate non-read-only and non-destructive; description reinforces non-destructive archival behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences efficiently cover purpose, operations, archiving, and alternatives. No redundant or filler content; front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does and key behavioral aspects, but lacks mention of required parameters (project, name) in description, and does not explain return value or error conditions. Given 6 params and no output schema, more contextual information would improve usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description lists operations (find/replace, append, prepend) but does not detail parameters like 'project' or 'append'/'prepend' semantics. Schema covers 50% of parameters with descriptions; description adds context but does not fully compensate for undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'edit' and resource 'text/report asset', enumerates operations (find/replace, append, prepend), and mentions versioning and archiving. Explicitly distinguishes from image editing tools, effectively disambiguating from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit alternative for image types ('use refine_media or image generation instead'), guiding when not to use this tool. Lacks mention of other potential text editing tools among siblings, but the directed alternative is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint true and destructiveHint false. The description adds context by noting 'only provided fields are set,' implying partial updates and idempotency. It doesn't contradict annotations and enhances understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that each add value. The first sentence explains the action and scope, the second provides workflow guidance. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool without output schema, the description covers the core action and workflow context but lacks details on error handling, return values, or behavior when fields already exist. Adequate for basic use but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (8%), so the burden falls on the description. The description lists the 11 field parameters that can be set, but doesn't add type, constraints, or relational context beyond what the schema provides. It's helpful but not deeply informative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Record website-sourced details on a lead' and lists the specific fields it can set. It distinguishes itself from sibling tools like add_lead or set_lead_status by focusing on enrichment from website data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use the pull_lead_website prompt to fetch + extract these from the lead's site first, then persist them here.' This clarifies the intended workflow and when the tool should be applied, though it doesn't list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds value by detailing the return payload (brand kit fields, generation instruction, CSS snippet, missing fields), which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key components, no filler. First sentence lists output, second gives usage advice. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description sufficiently outlines the rich return structure (brand kit, instruction, CSS, missing fields). It covers what's needed for the intended use case, though could hint at error conditions or format nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but does not explain the 'project' parameter (e.g., ID vs. name). It merely says 'the project's brand kit,' which is vague. Additional detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the project's brand kit, listing specific components. It also distinguishes it from the sibling write tool 'set_branding' by saying 'Call this before generating any branded asset,' implying read-only retrieval for consistency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use before generating branded assets for consistency. However, it does not explicitly exclude alternative tools or mention when not to use, missing a chance to differentiate from 'set_branding'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds value by stating the error condition on missing ID. This is useful behavioral transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the key action and result. No extraneous words, every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description specifies 'full company record including its contacts', which is vague but acceptable for a simple retrieval. It could describe the return format more explicitly, but it is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 50% of parameters, and the description does not add new parameter information beyond what is in the schema. The schema already documents 'id' as a slug from list_companies, and 'project' is self-explanatory. The description adds no extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a full company record including contacts, with a specific verb ('get') and resource ('company record'). It distinguishes from sibling tools like list_companies and add_company by specifying the scope and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to get a complete company record) and mentions error handling ('throws if id is not found'). It does not explicitly contrast with alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint true. The description adds that the tool returns null-ish on missing documents, providing safe, expected behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, no extra words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains return value and slug behavior, but does not mention the project parameter or its purpose. With no output schema, this omission reduces completeness for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only slug described). Description adds that slug accepts titles and gets slugified, but project parameter remains unexplained, leaving a gap for agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool description clearly states it reads a single knowledge base document's full markdown content by slug, with fallback to title slugification. This distinguishes it from siblings like list_kb_docs, search_kb, and add_kb_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading a specific document by slug, but does not explicitly exclude other use cases or mention when to prefer sibling tools like search_kb. It is clear but lacks alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=true. The description adds behavioral details: content encoding (UTF-8 vs base64), revision history with prompts, and the effect of parameters. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but packs many details into one sentence. It is front-loaded with the core purpose. Slightly dense but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description lists what is returned (metadata, size, content, revision history). For a read-only view tool, this is sufficient. Parameters are covered adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains version and withContent parameters beyond their schema definitions, and clarifies how content type depends on asset type. Schema coverage is 50%, but the description compensates well for the undocumented project parameter and adds context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'view' and the resource 'media asset', specifying what is returned: metadata, size, content (with encoding details), and revision history. This distinguishes it from siblings like list_media (which lists all) and edit_media (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives guidance on passing a version id and setting withContent:false, but does not explicitly state when not to use this tool or mention alternatives. It implies usage context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by detailing the output structure (grouped bugs, sorted by count, unlinked bugs) and the purpose of surfacing risk. Since readOnlyHint is already true, the description enhances understanding of the tool's behavior without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no wasted words. It front-loads the key information ('Regression view') and efficiently conveys grouping, sorting, purpose, and a reference to a related tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output format and purpose well for a read-only tool, but it omits explanation of the 'project' parameter and the exact structure of the returned data. Given the simplicity, it is mostly complete but could be improved with parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'project' has no description in the schema (0% coverage), and the tool description does not explain its meaning or expected values. The agent lacks guidance on what project to specify, which is a significant gap for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a 'regression view' with bugs grouped by linked features, sorted by open-bug count, and includes unlinked bugs. It distinguishes itself from sibling tools by referencing link_tasks to populate the view and specifying the unique grouping and sorting behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool by stating it surfaces which shipped features are at risk and references link_tasks to populate the view. However, it does not explicitly state when not to use it or provide direct alternatives beyond link_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds valuable behavioral details like 'most-recent first' ordering and the inclusion of a 'velocity rollup' in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences convey the core purpose, ordering, optional filtering, and output, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with clear annotations, the description covers ordering, optional filter, and return type. It lacks detail on the velocity rollup and pagination behavior, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and three parameters, the description only partially explains one parameter ('ticket' via 'optionally filter to one ticket'), leaving 'limit' and 'project' undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read work-log entries' with a specific verb and resource, distinguishes from sibling tools (e.g., 'log_work' for creation), and adds ordering and filtering details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for reading work-log entries with optional ticket filtering, but does not explicitly exclude alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=false. The description adds detail on what the brief includes and the optional eta based on project config, providing value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and each sentence adds value. It includes a specific reference (FBMCPF-269) which is slightly opaque but does not waste space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return content comprehensively (scope, details, files, etc.). It is complete enough for an agent to understand what the tool provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the parameter names 'ticket' and 'project' are self-explanatory. The description mentions 'one ticket' and 'project config', providing some context but no explicit parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it assembles a focused brief for one ticket, listing specific components: scope, linked-issue details, code location, project prompt, scratchpad mentions, work log, files to read, and definition of done. This distinguishes it from sibling tools like get_task or list_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use it ('before you work it') and provides a usage instruction ('Read the files it points to rather than dumping them'). It does not explicitly exclude alternatives, but the purpose is clearly scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description focuses on ordering behavior (newest-first vs soonest-first for upcoming:true) and filtering, adding value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that conveys purpose, ordering, and filter options efficiently. Could be slightly restructured for readability, but no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list with filters) and no output schema, the description covers the main aspects: resource, ordering, and filters. Could mention return type (list of bookings) but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must compensate. It explains the status enum values, the effect of upcoming:true, and implies project is required. However, the company and project parameters are not fully described (e.g., project identifies the board).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and resource 'bookings', clarifies ordering 'newest-first', and differentiates from sibling tools like cancel_booking and other list_* tools by focusing on booking-specific filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states filtering options by company, status, or upcoming flag. Provides context for ordering based on filter. Lacks explicit exclusion or alternative tools, but the use case is straightforward for a list endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only. Description adds that it returns a list of specific fields sorted alphabetically. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, clear and efficient. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides return fields and ordering. No output schema, but description covers the main info. Could mention pagination or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (product described, project not). Description adds value for product but does not mention project, leaving it undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists CRM companies with specific fields and alphabetical ordering. Distinguishes from sibling tools like get_company or add_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains the product parameter for filtering. Does not directly state when not to use it, but context with sibling tools implies usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the readOnlyHint annotation by specifying what data is returned (slug, title, updatedAt, size, excerpt) and what is not (full body). This helps the agent understand the tool's limits. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loading the action and resource, and includes key details. Every word serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one required parameter and no output schema, the description covers the essential behavior, return fields, and a key distinction. Missing details like pagination or sorting are not critical for a basic list, so completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the one required parameter 'project'. The description only implicitly ties it to 'a board's kb/docs', offering no format, examples, or constraints. With low schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'kb/docs', and the specific fields returned (slug, title, updatedAt, size, excerpt). It also explicitly distinguishes itself from a related tool (get_kb_doc) by noting that it does not return the full body.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear alternative ('use get_kb_doc for that') for when the full body is needed, implying when not to use this tool. However, it does not explicitly mention other sibling tools or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses what is returned (fields) and what is not (full raw text), complementing the readOnlyHint annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence front-loading purpose and listing return fields; no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool with one parameter and no output schema; covers return shape and distinguishes from full-text retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter description coverage; the description does not explain the 'project' parameter beyond tool context, missing opportunity to clarify its meaning or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists a board's sources/library with specific fields (slug, title, etc.) and distinguishes from get_source by noting it returns only excerpts, not full raw text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly differentiates from get_source for full text, providing guidance on when to use each. However, no explicit when-not-to-use or context for alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only ('Read-only — apply model choices with update_task labels if you want them stuck'), which aligns with the readOnlyHint annotation. It also describes the output and side-effect-free nature, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single long paragraph that conveys much information, but it is front-loaded with core functionality. It could be more concise by splitting into separate sections for core vs. optional planLimits behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and absence of an output schema, the description provides a thorough overview including return values and special conditions. It lacks error cases or budget insufficiency handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 50% of parameters have schema descriptions, but the description adds context for 'days' (greedy load-balance) and explains how parameters affect output. However, 'project' remains undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it maps a token budget onto the open queue before spending, with specific actions like assigning tickets to days and reporting splits. However, it does not explicitly differentiate from sibling tools like 'plan_work' or 'daily_plan'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions optional sprint restriction and a condition for an enhanced result when planLimits is set. It implies usage right before spending the budget but lacks explicit when-not-to-use or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the current copy is archived first, making the revert undoable, which adds behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). This helps agents understand the non-destructive nature and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core action and key behavior, then provide a useful usage hint. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately explains the revert process and where to find version ids, but lacks information about the return value (no output schema) and any prerequisites like permissions or state requirements. With 3 parameters and no output schema, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the 'version' parameter is explained in the schema, but the description adds context by mentioning get_media for version ids. However, 'project' and 'name' parameters lack any description or guidance beyond the schema, so the overall coverage is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Restore a prior version of an asset as the current one', which is a specific verb+resource action. It distinguishes itself from sibling tools like get_media (read) and edit_media (modify) by focusing on version restoration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use get_media to find the version id, helping agents understand the prerequisite. However, it does not specify when not to use this tool or mention alternative tools for other revert scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key traits (idempotent, not read-only, not destructive), and the description adds behavioral details: replacement and deduplication. It confirms idempotency by noting replacing the list has the same effect repeatedly. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, then additional context. No fluff; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, replacement behavior, deduplication, and downstream use (filtering in list_companies). For a 3-parameter set operation with no output schema, it is fairly complete, though it could mention the effect of an empty array or success indication.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with only two of three parameters (company, products) described in the schema and none in the description. The missing 'project' parameter lacks description entirely, and the description does not add meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'records which products a company uses/owns', specifying the verb (record/set) and resource (company's products). It distinguishes from siblings like add_product and remove_product by noting it replaces the list and is de-duplicated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'replaces the list', indicating it is for full replacement rather than additive operations. It also provides context on surfacing and filtering via list_companies, but stops short of explicitly naming additive alternatives, relying on implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description adds meaningful behavioral context: writes go specifically to the MCP-managed config and never to legacy project_config.json; only provided fields change; and websiteLocation's default fallback to <project>/site/ is disclosed. This gives the agent safety-critical knowledge about where state is persisted that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three front-loaded sentences: core action first, then key field semantics, then remaining field groups. It is dense (~110 words) but every clause earns its place; the parenthetical list of website tools is slightly long but useful for disambiguation. For a 32-parameter tool this is appropriately sized, not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity (32 params, nested objects, no output schema), the description covers the most consequential cross-field behaviors: partial updates, safe write target, pointer fields with defaults, and the voice-profile feature family. Minor gaps remain — return value/response shape is not mentioned and per-field defaults are only in the schema — but the schema's rich per-property descriptions compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 78%, the schema already documents most parameters well. The description adds genuine value on top for the least-obvious ones: codeLocation and websiteLocation's pointer semantics (which tool families consume them, the 'leave unset' default), and the voiceLint/etaHints groupings. It wisely avoids re-listing all 32 parameters and instead clarifies cross-cutting behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Update a board's settings') and immediately adds the partial-update semantic ('only provided fields change'). It clearly distinguishes itself from siblings like get_project_config (read), set_global_config (global scope), and set_branding (branding-only) by scoping to a single project's MCP-managed config and naming the field families it configures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys clear usage context: it explains that websiteLocation redirects website tools to a shipped site outside the pad (and what happens when left unset), and it warns 'never mutates legacy project_config.json' — an important exclusion. However, it never explicitly says when to prefer this tool over alternatives like set_global_config or set_branding, nor states 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, non-destructive, and writable. The description adds context about the effect (maps correctly, falls into areas) beyond the schema, though it does not detail permissions or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no output schema, the description is minimal. It covers the core action but lacks guidance on project/ID context, expected return, or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description clarifies purpose of lat, lng, and city parameters (coordinates and/or city), adding value beyond the schema which has only 20% description coverage. However, it omits explanation for 'id' and 'project' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a lead's location (coordinates and/or city) for correct mapping and area assignment, distinguishing it from siblings like set_lead_status or add_lead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when setting coordinates or city for mapping but does not explicitly state when to use it versus alternatives like leads_map or set_lead_status, nor 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=false and destructive=false, so the description correctly implies a non-destructive write. It adds that the tool returns the new comment and total count, and mentions threading behavior, covering key traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key differentiator. No wasted words, essential information prioritized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value. It covers the main purpose and threading behavior. Lacks error conditions or edge cases, but sufficient for a simple create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), so baseline is 3. The description adds context for parentId (where to obtain it) but does not elaborate on other parameters beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Add') and the resource ('threaded comment to a gallery asset'), and distinguishes it from pin annotations, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use parentId for replying to existing comments, implying when to include it. It distinguishes from pin annotations but could be more explicit about when not to use this tool vs alternatives like list_media_comments or remove_media_comment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show idempotentHint=true, consistent with 'create or update' semantics. The description adds useful behavioral context: the registry is stored in project config and the label-based ticket assignment mechanism. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose. Every sentence adds value: first sentence defines the action, second explains labeling, third ensures compatibility. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description covers creation/update behavior, persistence, and interaction with the ticket system. It is sufficient for an agent to understand when and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83% (5 of 6 parameters described). The description mentions 'optional start/end dates and a one-line goal' but adds minimal value beyond the schema, which already documents constraints like name format and goal being one-line.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create (or update) a named sprint on a board') and the specific resource (sprint with optional dates/goal). It distinguishes from sibling tools like assign_sprint by mentioning the label mechanism and that tickets join via sprint:<name> label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the sprint registry is persisted in project config and references assign_sprint for ticket assignment. It also notes compatibility with label-only sprints from the board UI, providing context for when to use this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety flags, so description adds value by stating it returns HTML and optionally writes to media gallery. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence that front-loads purpose and adds essential details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: purpose, output (HTML), optional save, and linking hint. Lacks explanation of side effects beyond save, but adequate for a clear tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds context for 'company' by mentioning contacts and tickets, and 'save' behavior is explained. However, 'project' parameter is not described, and schema already covers 67% of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool builds a per-customer portal page with contacts and linked tickets, using specific verbs and resources. Distinguishes itself from sibling tools like list_companies or add_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context for building portals and mentions linking tickets with link_customer_ticket as a prerequisite. No explicit when-not or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint true and destructiveHint false, and the description adds that apply:true writes labels (a mutation), explains the budget interpretation, and describes the return value (dispatch groups). No contradictions are present. The description adds useful behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence adds value: purpose, budget, model assignments, effort levels, apply behavior, return type, and pairing advice. It is not overly verbose and is well-structured, though a slight separation of concerns could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return value (dispatch groups with parallel sub-agents) and references internal code for further details. It covers behavior, parameters, output, and usage context (pair with daily_plan prompt). The tool is complex, and the description provides sufficient completeness for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3 of 4 params have descriptions), and the description adds meaning: it explains the budget in terms of days/weeks, the apply parameter's effect, and the model roster with values (fable, opus, etc.) that are not captured in the schema. The description compensates well for the undocumented project parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Plan TODAY') and resource ('priority queue'), and specifies the scope (daily slice, default budget). It distinguishes from siblings by its unique function of assigning models and effort levels, which is not covered by other planning tools like 'plan_work' or 'plan_budget'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use (daily planning, with a budget model) and mentions pairing with a prompt, but does not explicitly state when not to use or list alternative tools. There is no guidance on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the read-only nature noted in annotations ('Read-only'). It does not add significant behavioral context beyond what annotations already provide (no mention of performance, pagination, or side effects). For a read-only tool with good annotation coverage, this is adequate but not excellent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat dense but front-loads the main purpose and lists components efficiently. It could be slightly more concise, but every sentence adds value and no word is wasted. Structure is logical (purpose, components, formats, read-only note).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (merging multiple audit primitives) and lack of output schema, the description is remarkably complete. It enumerates all included data sources, the board-level summary, and the three output formats with their intended use cases. No critical gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 80% of parameters with descriptions, but the description adds meaning beyond the schema by explaining that includeCommits affects speed ('faster') and that maxCommits limits linked commits. This provides practical usage context absent from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('export') and resource ('compliance & traceability report'), explicitly distinguishing it from sibling tools like get_ticket_history, get_work_log, and drift_report by positioning it as a 'unified' merge of those primitives. This makes the tool's purpose highly distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: for an audit of one ticket or the whole board, with format options. It does not explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to differentiate from granular sibling tools. Lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds value by explicitly stating 'Read-only' and explaining the round-trip relationship with 'import_tasks', which goes beyond the annotation's binary flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant information. The most critical details (purpose, formats, round-trip, read-only) are front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and no output schema, the description covers the essential aspects: purpose, formats, read-only nature, and relationship to import_tasks. It could mention how the exported data is delivered (e.g., download), but that is often implicit for export tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies the 'format' parameter by listing its enum values (json, csv, markdown). However, it does not add meaning for the 'project' parameter beyond the inferred board identifier, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export', the resource 'a board's tasks', and the output formats 'json, csv, or markdown'. It also mentions the use case 'for use outside FeatureBoard (e.g. sharing with a PM tool)' and distinguishes from the sibling 'import_tasks' via the round-trip note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use context (exporting for external use) and implicitly indicates 'import_tasks' as the reverse operation. However, it does not explicitly state when not to use this tool or list alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds extensive behavioral details: fallback logic for elapsed time, last event age calculation, token spend ratio, stalled flag definition, lastDispatch structure, and summary aggregation. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but efficiently packed with details, front-loaded with purpose. Each sentence adds value, though it could be slightly more concise without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully explains the return format: each ticket's fields, lastDispatch object, summary statistics, and special cases (capCost null). Annotations are present. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters described). The description does not add new semantic info for parameters beyond the schema, except reinforcing stallMinutes default and context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Live snapshot of the board's currently-running work: every In Progress ticket with elapsed time...' clearly defining the tool's purpose. It distinguishes itself from sibling tools like get_board or get_task by focusing on agent monitoring metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage ('Use it to see what's underway...') and mentions pairing with churn mode, but does not explicitly state when not to use it or compare to alternatives like get_live_activity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the agent knows it's safe. The description adds valuable detail about resolvedGitMode and gitModeSource, and that git is disabled by default, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, behavior, and key details. Front-loaded with the main action and resource, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description fully explains what is returned (fields and their resolution order). It is complete given the tool's complexity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter 'project' with no description (0% coverage). The description does not elaborate on the 'project' parameter (e.g., format, requirements, or examples), leaving the agent to infer from the required flag. With low schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads git integration settings, lists the specific fields (enabled, remote, branch, etc.), and distinguishes from siblings like set_git_config and get_global_config. The verb 'Read' and resource 'project's optional git integration settings' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the resolvedGitMode derivation and default disabled state, providing context for when to use this read operation. However, it does not explicitly contrast with alternatives like get_global_config or set_git_config, though the context of reading vs writing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description confirms read behavior with 'Read'. It adds context beyond annotations by detailing the settings (gitMode, planLimits) and their structure, including optionality ('when captured'). No side effects or contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, comprising four sentences that front-load the purpose. It includes relevant details but has minor redundancy (e.g., referencing tickets FBMCPF-278/279). Overall, it is well-structured and earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the tool's output, including the default gitMode value and the detailed structure of planLimits with its fields. It also notes the storage location. Given no output schema, this is comprehensive and sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero input parameters, so the input schema is trivially covered at 100%. Per the rubric, 0 parameters baseline is 4. The description adds value by explaining the output structure of the settings, which is helpful for interpreting the result, even though it does not address input parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads account-wide settings, specifies the verb 'Read' and resource 'account-wide settings', and distinguishes from siblings like set_git_config by noting that project overrides use the latter. This provides specific and differentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool ('applies across every project unless a project overrides them via set_git_config') but does not explicitly mention alternatives like get_git_config for reading project-specific settings. No direct when-not or exclusions are provided, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds value by detailing the conditional output shapes (list, manifest, markdown) and the source (close_sprint reports). This goes beyond the safety signal to explain dynamic behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each covering a distinct usage scenario. Front-loaded with the purpose, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return types reasonably: list of sprints, manifest+audiences, markdown. Minor gap: the term 'manifest' is not defined, but the overall completeness for a read tool is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for sprint (omit to list) and audience (which report), but the required 'project' parameter lacks explanation both in the schema and description. With 67% schema coverage, the description partially compensates but leaves a gap for project.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads close-out reports from close_sprint and distinguishes three distinct behaviors based on parameter presence: listing sprints, showing manifest+audiences, or returning a specific audience report. This specificity differentiates it well from sibling get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by explaining what happens with different parameter combinations (no sprint, sprint only, sprint+audience). It does not explicitly state when to avoid or provide alternatives, but the use cases are clear enough for an agent to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate modification and idempotency; description adds details about cycle rejection and parameter effects, going beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main verb, no redundancy, each part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, kind variants, and a behavioral constraint (cycle rejection). Missing return value info but acceptable given no output schema and good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Explains ticket and linkedIssue roles and kind enum, but does not describe the project parameter. With 0% schema coverage, more explanation of all parameters would be better.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it relates two tickets, explains the two kinds with examples, and distinguishes from sibling tools that perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use each kind ('linked' vs 'blocks'), including cycle rejection. Could be improved by noting when not to use this tool, but alternatives are not available in siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only. The description adds the specific fields returned, which provides useful detail beyond the annotations. No mention of pagination or limits, but the tool is likely simple enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence followed by a clarifying clause. No unnecessary words; front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return structure. It covers the core functionality well, though missing potential details like ordering or pagination. Annotations add safety context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only ticket has a description). The description adds meaning for 'ticket' by stating it filters decisions, but 'project' remains undocumented. With partial coverage, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a project's ADR log and returns structured entries. The verb 'read' and resource 'ADR log' are specific, and it distinguishes from the sibling tool 'add_decision' which writes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to list ADRs) and how to filter by ticket. It does not explicitly state when not to use it or name alternatives, but the context is clear given siblings like 'add_decision'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which are neutral), the description discloses that the update is surfaced on get_metrics and get_health, that a staleness hint appears when older than 7 days, and that voiceLint scoring (when enabled) attaches a 'voice' result as warn-only. These are non-obvious side effects that add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each purposeful. First sentence states the core action. Second lists parameters. Third explains downstream effects. Fourth details optional behavior. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers tool purpose, parameters, behavior, and integration points. It could mention prerequisites (project existence) or error cases, but for a simple append tool, it is sufficiently complete given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides enum values for 'health' and a description for 'narrative', but no description for 'project'. The description reinforces the health enum values and clarifies narrative as free-text, but does not explain the project parameter format or constraints. With 33% schema description coverage, the description adds some value but does not fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action: 'append a dated narrative status update to the project's updates.md pad'. It distinguishes itself from heavier sprint close-out reports and references sibling tools like get_metrics and get_health for how the update is surfaced. The verb 'append' and resource 'updates.md pad' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool ('a lightweight health check-in that lives between the heavier sprint close-out reports'), providing clear context. However, it does not explicitly state when not to use it or list alternatives, though the unique purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides rich behavioral details beyond the annotations, including model caching, offline usage, fallback reasons, and mode behavior. It does not contradict any annotations and adds context that helps the agent understand the tool's behavior in various conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise, with each sentence contributing to understanding the tool. It is front-loaded with purpose and mode details, though it could be slightly shortened without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with nuanced behavior, and the description covers mode selection and fallback. However, without an output schema, the return value shape (e.g., fields in chunks) is not specified, leaving a gap for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3 of 4 parameters have descriptions). The description adds extra context for the 'mode' parameter by explaining its implications, but does not significantly enhance understanding of the 'project' parameter or the returned chunks. Overall, marginal value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs local retrieval over KB docs, code repo docs, and Done tickets, with specific retrieval methods (BM25, embeddings, hybrid). It distinguishes itself by mentioning zero model tokens and a two-stage hybrid approach, making its purpose distinct from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use hybrid vs lexical mode and covers fallback scenarios. However, it does not compare directly with sibling tools like 'search_kb' nor specify when not to use this tool, leaving some ambiguity among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond annotations: size cap, binary file handling, sandboxing to codeLocation. Annotations already declare readOnlyHint=true, so no contradiction. The description enriches behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences with the core purpose upfront. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is well-covered for a simple read operation: mentions sandboxing, size cap, binary handling. Missing explicit return format details (though 'content + line count' is stated). Adequate given lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, but the description implies that 'path' is relative to codeLocation and mentions a size cap (related to maxBytes). It does not explain 'project' or 'maxBytes' explicitly. Some value added but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a file under codeLocation as UTF-8 text, with size capping and binary flagging. It distinguishes from sibling tools by focusing on reading a single file, not listing or modifying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives (e.g., list_code_files). However, the purpose is straightforward enough that an agent can infer usage from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond annotations: dry-run by default, apply:true to write, and the refusal of updates until repair. Annotations already indicate idempotency and non-destructiveness, which align with the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, straight to the point, with no redundant information. It front-loads the core purpose and problem, then details the usage and a key behavioral note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple parameters, no output schema), the description adequately covers the problem, default behavior, application, and a constraint. It could optionally mention the return format, but it's not essential for a repair action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 50% description coverage (only 'apply' has a schema description). The tool description clarifies the 'apply' parameter's effect and the concept of a 'board' for the project parameter, adding moderate value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds duplicate ticket ids on a board and optionally renumbers them. It specifies the action (find, renumber) and the resource (ticket ids), and the context (legacy data collisions) makes it distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default dry-run behavior and how to apply changes, and notes that updates to duplicated ids are refused until repair, implying when the tool is needed. No explicit alternatives are given, but none are required given the specific task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations. Annotations indicate non-read-only, non-idempotent, non-destructive, and open-world. The description confirms it writes to a local CRM and interacts externally by returning a URL/email. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core purpose. Every sentence adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count, lack of output schema, and annotations, the description adequately explains the workflow: records locally, returns URL/email, then activate_license. It could be more specific about the output format, but it is sufficient for an agent to understand the flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all parameters. The tool description does not add extra meaning beyond the schema's parameter descriptions, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: starting the commercial licensing process. It specifies that it records the request locally for CRM and returns a URL and email to complete a signed agreement. It also distinguishes from the sibling 'activate_license' by noting to use that after a key is issued.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: to start a commercial license. It provides guidance on the next step ('After the licensor issues a key, use activate_license'), which implies when not to use it (before key issuance). However, it does not explicitly compare with other related tools or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint. The description adds behavioral context: the brand kit is stored on the board config, and by default applies to the project website. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded. Every sentence adds value: first defines purpose, second adds storage and default behavior. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 10 parameters and no output schema, the description covers the main use case (setting brand kit), mentions related tool (get_branding), and explains default side effect (apply to site). It lacks details on return value but that's acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has high description coverage (90%), so baseline is 3. The description lists key parameters but doesn't add new semantic depth beyond what the schema provides. It does reinforce the overall purpose of the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set', the resource 'project's brand kit', and the scope 'in one place'. It differentiates from sibling tool get_branding by noting 'retrieve it with get_branding'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on when to use (set brand kit) and mentions the alternative get_branding for retrieval. It also notes the default behavior of applying to the project website. However, it does not explicitly exclude other sibling tools that might set project configuration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses overwriting behavior (matches destructiveHint) and explains that once set, the work packet and definition-of-done are affected. This adds context beyond annotations (destructiveHint, idempotentHint). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences front-load purpose, then behavior, consequence, and workflow hint. Every sentence adds value with no redundancy. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with 6 parameters and good annotations, the description is sufficient: it explains purpose, overwrite behavior, downstream effect, and provides a workflow step. No output schema needed for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (4 of 6 parameters described). The description adds meaning by listing 'intent, assumptions, acceptance criteria, and open questions' which map to parameters, but it doesn't explicitly describe the 'project' and 'ticket' parameters, though they are implied. It adds some value but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a ticket's refined requirements pad with specific fields (intent, assumptions, acceptance criteria, open questions) and overwrites existing pads. It distinguishes itself from sibling tools, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use: after drafting content (reference to 'refine prompt') and to persist it. It explains the consequence (work packet carries requirements, acceptance criteria become DoD). However, it does not explicitly state when not to use or compare to alternatives, but sibling tools do not overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this by stating 'Read-only — it returns the stub, it does not create the file.' This adds value by clarifying the exact behavior (return vs. create). No contradictions or missing behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, usage, and behavioral clarification. No redundant or irrelevant information. It is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required parameters, the description covers what it does, when to use it, and what it returns. It lacks error handling or validation details, but with good annotations, it is fairly complete. A minor gap is the absence of parameter format guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains that the test stub is derived from the ticket's title/description and board code location, giving context for the project and ticket parameters. However, it does not describe parameter formats or valid values, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a boilerplate test file for a ticket, including path and node:test content, derived from ticket title/description and board code location. It is specific about the resource (test stub) and action (generate), and the label 'Agent-native fixtest' helps distinguish it from other test-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling the tool 'when creating or starting a ticket' and then writing the returned file, providing clear usage context. However, it does not mention when not to use it or compare with sibling tools like generate_test, which could cause ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations by explaining the partial update ('only provided fields change') and how to clear fields with empty strings. Annotations provide idempotency hint, which is consistent. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, front-loaded sentences with zero wasted words. Essential information is presented efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers partial update and clearing important behaviors. However, it does not mention required parameters or what the response contains. Mostly complete for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 29% schema coverage, description helps by explaining that updating only provided fields and clearing via empty string. However, it does not fully compensate for the lack of schema descriptions for name, project, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit a contact on a company' with explicit partial update behavior. Distinguishes from siblings like add_contact and remove_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Purpose clearly differentiates from add/create and remove, but no explicit when-not or alternatives are provided. Context is clear enough for standard CRUD.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. The description adds detail on the types of errors and warnings reported, confirming the tool's behavior 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence with no extraneous words. It efficiently communicates purpose, scope, and output types.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers what the tool does and its output categories. It lacks explicit return format but is sufficient for an agent to understand its function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'project' has no schema description (0% coverage). The description mentions 'the project's saved packaging.json', providing context that 'project' identifies a project, but does not specify format or allowed values. This partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs build-preflight packaging checks on a project's packaging.json. It specifies what it reports: hard errors (missing/invalid name/description) and advisory warnings (no keywords, missing displayName/longDescription). This distinguishes it from siblings like save_packaging_config and suggest_packaging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pre-flight validation before packaging, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The purpose is clear enough for an agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is safe. The description adds behavioral context by explaining the ranking method (keyword overlap and shared product), which helps the agent understand what the tool does beyond the schema. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with only two sentences. The first sentence defines the action, and the second provides usage guidance. Every word contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and usage but lacks details about the output format (e.g., how ranks are presented, what fields are returned). Given the tool has no output schema, the description could be more informative about the expected return value, which is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the two modes: using a bug ticket or providing an ad-hoc title/description. It also mentions 'shared product' which relates to the required 'project' parameter. Schema coverage is only 25%, so the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: given a bug, rank existing features by impact using keyword overlap and shared product. It uses a specific verb ('rank') and resource ('features'), and it distinguishes itself from sibling tools like 'log_bug' or 'get_regressions' by focusing on impact scanning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it when logging a bug to spot regressions and linkage candidates,' providing a clear usage context. However, it does not mention when not to use this tool or list alternatives, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds substantial detail: exactly one GET request to a specific URL, no request body (privacy), compares version locally, provides download links, and fails soft on network issues. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the primary purpose. Every sentence adds value: technical details, privacy assurances, behavior, and error handling. It is appropriately sized without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the tool's behavior comprehensively: action, URL, comparison, returned information, and error handling. It lacks only explicit output structure, but that is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, with 100% schema coverage. The description correctly implies no parameters are needed. Baseline for no parameters is 4, and the description aligns perfectly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it explicitly checks for a newer FeatureBoard release via an HTTPS GET request to a specific URL. It naturally distinguishes itself from all sibling tools, none of which perform update checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to explicitly check for updates) and clarifies that it never runs automatically (no polling or background checks). It also mentions soft failure handling. Though no explicit 'when not to use' is given, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), the description discloses the return value structure (structured fields and raw markdown) and the null return when no pad exists. This adds significant behavioral context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first describes the output structure, the second covers the null return. No unnecessary words or repetition. Efficiently front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a read tool with good annotations: it explains the return value (structured + raw markdown, or null) and the read-only nature. However, it does not address behavior when the ticket itself does not exist (e.g., error vs null), leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the 2 parameters (ticket, project). The description does not explain what these parameters represent or how they are used. With no parameter descriptions in the schema, the tool description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Read' and identifies the resource as a 'ticket's requirements pad'. It lists the structured components (intent, assumptions, acceptance criteria, open questions) and mentions raw markdown, clearly distinguishing from sibling tools like set_requirements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates this tool is for reading the requirements pad, but does not explicitly state when to use it versus alternatives like set_requirements or check_acceptance. The readOnlyHint annotation reinforces its read-only nature, but no exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds detail on what state is returned (steering.json fields and live snapshot) and confirms no mutation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence covers functionality and comparison, second adds usage guidance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, description covers return values comprehensively. Lacks parameter details but overall sufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description only mentions 'for a project' without specifying format, constraints, or example. Description adds minimal meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'read-only observability into the steering loop' and specifies it returns persisted and live state. It distinguishes from 'steer_project' by explicitly noting it does NOT run or mutate, making purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with 'steer_project' and gives a use case: 'Use it to answer where is steering at? without kicking off a new wave.' This tells when and why to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false. The description adds that it reads the project's test/ directory and feeds into multi-model eval, providing behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first delivers purpose, second adds technical context. No wasted words. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema present. The description hints at what is returned (variant names and model tier coverage) but does not specify format or structure. For a listing tool, this is adequate but not complete. Could be improved by noting the output type (e.g., array of strings).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 required parameters (ticket, project) with 0% description coverage. The description mentions 'for a ticket' implying the ticket parameter is a ticket identifier, and project is the project name, but does not elaborate on format or constraints. Minimal value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List' and resource 'per-model test variants' for a specific context (ticket, project). It also mentions the file pattern and purpose (feeds multi-model eval), distinguishing it from siblings like list_test_pages or generate_multi_model_tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description specifies when to use: to list test variants for a ticket and see model tier coverage. It does not explicitly state when not to use or suggest alternatives, but the context is clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with readOnlyHint=true annotation, adds behavioral context: worktreeDir is outside the repo by default, and the ticket id derivation. No contradictions. Adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with the core purpose. Each sentence adds value: operation, returned fields, extra context, and read-only note. No redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one param, no output schema), the description completely covers what the agent needs: what it lists, the fields returned, and a pointer to a related caveat. Adequate for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'project' is described as the project identifier for the code repo. With 0% schema description coverage, the description provides meaningful semantics beyond the type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists git worktrees for a project's code repo, specifying the exact fields returned (path, branch, HEAD, isMain, ticket id) and the worktreeDir. This distinguishes it from siblings like create_worktree or cleanup_worktree.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Read-only' and references a caveat on create_worktree, but does not explicitly state when to use this tool versus alternatives or when not to use it. Usage is implied but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: ordering, null return when empty, and conditional eta field. Consistent with readOnlyHint annotation. Adds value beyond annotations by explaining the ordering algorithm and the eta condition (FBMCPF-269). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear structure: purpose, ordering details, and edge case. Front-loaded with core functionality. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, ordering, and null return, but misses explanation of the 'type' filter and return structure details beyond eta. With no output schema, some additional description of return format would improve completeness. Still sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description does not explain the 'type' parameter (enum: all, feature, bug) or its default. The 'project' parameter is implied but not explicitly described. Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return the next open ticket to work', specifies the resource (ticket with status Todo or In Progress), and explains the ordering logic (In Progress first, then earliest due date, then oldest). Differentiates from siblings like 'next_wave' and 'list_tasks' by focusing on single sequential task retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so you can pull work one item at a time' implies sequential single-task usage, but does not explicitly state when to use this tool over alternatives like 'next_wave' or 'plan_work'. However, the preference logic provides clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: deliberate outbound egress (openWorldHint), no destructive mutation (destructiveHint false), no-ops on missing config/allow-list, and failure mode (returns warning, never throws). Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy: immediately states action, explains scope, then clarifies edge cases. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: input parameters, configuration dependency, no-op conditions, and error behavior. No output schema needed as return behavior is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with descriptions for text and event, but description adds behavioral context (e.g., event must be in allow-list) linking to parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Post a message to THIS project's user-configured Slack incoming webhook', identifying the tool as a Slack notifier specific to the current project, distinct from all sibling tools which cover other domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes conditions for use: it only sends to the user-configured Slack webhook, no-ops when unconfigured or event not in allow-list. Does not list alternatives, but absence of other Slack tools makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with annotations (readOnlyHint=true, openWorldHint=false) and adds rich behavioral context: algorithm (throughput, priority queue), that it 'suggests' and 'flags', and that it is read-only. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose. Every sentence adds value: algorithm, outputs, and read-only note with next step. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is moderately complex (algorithm, multiple outputs) and no output schema. The description covers what outputs to expect (projected dates, suggestions, flags). Could mention edge cases or errors, but sufficient for a prediction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%) with only 'asOf' having a description. The tool description does not explain the 'project' or 'type' parameters in detail. It mentions walking a priority queue but does not link this to parameters, leaving the agent to infer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states it estimates completion dates using backlog and throughput, walks priority-ordered queue, suggests due dates, and flags slips. It clearly distinguishes from sibling tools as no other sibling does due-date prediction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for planning by noting 'Read-only — apply a suggestion with update_task if you want it stuck.' It does not explicitly state when not to use or list alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint=true and openWorldHint=false are supplemented by detailed behavioral disclosure: deterministic assembly, no model calls, return structure (questions, sources, spec, saveInstruction, model suggestion), and skip behavior. The description adds rich context about what the tool produces and how it interacts with other tools (e.g., add_kb_doc), far beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise given the complexity, front-loading the action and outcome. However, it includes implementation references (FBMCPF-263, FBMCPF-264) that may be noise for an agent. The structure clearly lists return components, but the inclusion of ticket IDs for internal tracking reduces readability. Still, it conveys essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive: it covers all return fields (questions, sources, spec, saveInstruction, model), conditional behavior (skip on off, forced on), and config/label interaction. Without an output schema, the description fully explains the expected output. This completeness, combined with annotations, makes the tool well-specified for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the two parameters (ticket and project). Although 'ticket' is implied in the purpose ('for a ticket'), the 'project' parameter is not described at all. No details are given about expected format, values, or constraints. The description focuses on behavior but neglects input semantics, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'deterministically assemble a research REQUEST packet for a ticket BEFORE implementation'. It specifies the exact resource (research request for a ticket) and action (assemble), and the mention of 'no model calls' distinguishes it from generative tools. Among siblings like search_kb or append_research, this tool's unique role is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use it before implementation, skip when research is off, and force with labels. It explains return behavior for both on and off states. However, it does not explicitly mention alternative tools or when not to use it, which would be helpful for an agent to decide between this and other research-related tools like search_kb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety hints, so the description carries the burden. It discloses sidecar creation (.meta.json), persistence behavior, and encoding options. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no waste. First sentence covers core purpose and formats; second clarifies a critical naming rule. Front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains core functionality and sidecar generation but does not mention the return value or behavior on conflict (e.g., overwrite). For a 10-parameter tool with no output schema, this leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 70% of parameters with descriptions, and the description adds useful context: naming convention ('plain filename with extension'), encoding usage, and that brandWords defaults to project settings if omitted. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save' and the resource 'generated asset into a project's media/ folder', specifying file types (HTML, SVG, image) and encoding. It distinguishes from siblings like list_media and edit_media by focusing on creation and persistence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after generating content and notes that list_media reads the metadata sidecar. However, it does not explicitly state when not to use this tool or mention alternatives like edit_media or revert_media.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses append-only behavior, auto-numbering (ADR-<n>), and that relevant ADRs surface in work packets. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with this, and the description adds useful context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the core action and appends key details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, behavior, and key constraints. It does not mention return values or error handling, but for an append tool with no output schema, this is adequate. Minor room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, close to the high threshold. The description broadly maps to the parameters but does not add significant meaning beyond what the schema already provides (e.g., that 'tickets' is an array). Qualitative context is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it appends a new ADR to a project's decision log, specifies the fields (context, decision, consequences, tickets), and distinguishes from sibling tools like list_decisions. The verb 'append' and resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is append-only and never rewrites prior ADRs. It also hints at the value of ADRs surfacing in ticket work packets. However, it does not explicitly state when not to use it or mention alternatives for editing or viewing decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors (creates doc on first call, appends later, findings accrue in kb) beyond the minimal annotations, though could mention potential side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a simple append tool given no output schema; covers creation vs appending and durability, but could elaborate on ticket existence assumptions or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds little beyond the input schema; the 'finding' description is already present in the schema, and 'project' remains undefined. Schema coverage is moderate (67%), so description should compensate more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Capture ONE research finding into a ticket's durable research doc' with a specific verb and resource, and explicitly distinguishes from sibling tool append_scratchpad.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Prefer this over append_scratchpad' and advises calling it repeatedly during research, giving clear when-to-use/not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive. Description adds beyond: explains refusal behavior, file writing, Slack posting (error tolerance), and rollover modes. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph covers all behaviors without redundancy. Front-loaded with core action. Could benefit from slight structuring (e.g., bullets for modes) but remains efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a complex tool: covers parameters, conditions, outputs, error handling, and rollover modes. Lacks explicit return shape details but notes 'result shape unchanged with rollover section', which is adequate given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% (project lacks description). Description greatly enriches parameter understanding: force effect, rolloverMode behavior, nextSprint usage, and output paths. Significantly adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Close a sprint and generate four audience-specific close-out reports' with a specific verb and resource. It distinguishes from siblings like create_sprint and list_sprints by detailing the unique outcomes (reports, rollover handling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (finalize a sprint, generate reports) and provides conditions (refuses with open tickets unless force). It doesn't explicitly list alternatives but context from siblings makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; the description reinforces this as 'Read-only' and adds behavioral detail about the return format (prompt, path, instruction) and manual execution requirement. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with all essential information front-loaded. No redundant text; every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description adequately covers the return format (prompt, storage path, instruction) and the intended workflow. It leverages sibling context and annotations. Minor gap: does not explain the 'instruction' field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so baseline is 3. The description adds value by explaining the default model tiers and how they surface different failure concepts, which is not in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fans a generation prompt across model tiers (fable, opus, sonnet) and returns per-tier prompts and storage paths. It distinguishes itself from siblings (suggest_test_stub, generate_test) by mentioning it builds on them and by requiring submission to save_generated_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies usage for a bug/ticket and provides explicit workflow: run each tier yourself then submit to save_generated_test. It references sibling tools but lacks detailed exclusion criteria for when to use this vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond readOnlyHint: uses env var, normalizes data, graceful degradation, returns URL on failure. No contradictions to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loaded with purpose, then degradation behavior. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but describes return as 'normalised numbers' and 'exact request URL'. Lacks explicit structure of the returned data, but sufficient for a simple proxy tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters with descriptions. Description doesn't add extra detail for parameters beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'read' and specific resource 'site traffic (analytics proxy)'. Description distinguishes from siblings by mentioning third-party providers (Plausible/umami) and the normalization behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States degradation behavior and return of request URL when unconfigured, hinting at alternative (fetch yourself). Lacks explicit when-not-to-use or comparison to other tools like get_metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to assert read-only status. Instead, it adds rich behavioral details: exact fields returned (dates, fallback logic for startedSource, per-day rollups, board-wide data), and optional date filtering. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and is comprehensive without redundancy. It efficiently conveys all needed info in a few sentences, though slightly longer than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description fully and explicitly details return data: per-ticket fields (createdDate, startedAt with source, completedAt, status/grouping/color fields, cumulative tokens, per-day rollups) and board-wide byDate[] rollup. This covers all expected output for a read-only timeline tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (from, to, project). The description adds meaning for 'from' and 'to' by stating they filter spans based on overlapping worked windows, which reinforces the schema descriptions but doesn't add new semantics beyond that. The 'project' parameter is not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Per-ticket worked spans for the board's piano-roll Timeline view, in one read pass.' It specifies the verb (get), resource (timeline data), and scope (per-ticket), effectively distinguishing it from siblings like get_board.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description sets clear context for when to use the tool (Timeline view) and mentions it's a single read pass. However, it does not explicitly state when not to use it or name alternative tools, so it lacks full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with a write operation. The description adds transparency by noting that dryRun allows preview without writing, and explains auto-detection of format, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, then lists supported formats, auto-detection, and dry run. Every sentence is informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers supported formats, auto-detection, dry run, and default type. It lacks details on error handling or size limits but is sufficiently complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%) with 4 of 5 parameters described. The description adds value by explaining the overall behavior, format auto-detection, and dry run functionality, clarifying the use of parameters like format and content beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports a backlog from raw text into a board, specifies multiple formats (markdown, CSV, JSON), and mentions auto-detection, distinguishing it from sibling tools like add_feature or add_features_bulk which handle single or multiple tasks in a different manner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (importing a backlog) and provides guidance on formats and dry run, but does not explicitly contrast with alternatives or state when not to use it. The context is clear enough for an AI agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden. It discloses that the tool optionally creates a project, returns all created tickets, and mentions the etaHints feature (eta estimates and totalEta roll-up). While it doesn't cover error handling or partial failures, it provides useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (four sentences) with no redundant information. Every sentence adds value: purpose, usage, return value, and a specific behavioral note. Front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested arrays) and lack of output schema, the description sets reasonable expectations. It covers the main behavior, optional project creation, and return of tickets. However, it could be improved by noting error handling, limits, or the format of returned tickets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20%, and the description does not detail each parameter's meaning beyond what is in the schema. However, it does clarify that the `dependsOn` indices refer to the combined list (features then bugs), and mentions the optional project creation. This adds some value but is insufficient for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: breaking a request into board items (features and bugs) in one step, optionally creating a project. It explicitly distinguishes this from sibling tools by calling it the 'FIRST step' and a bulk operation, contrasting with individual ticket creation tools like 'add_feature' or 'log_bug'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this as the FIRST step when starting a substantive request, then work the tickets one at a time.' This tells the agent to use this tool before individual ticket operations, implying it should not be used for small or single-item requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations that mark destructiveHint=true, the description adds important behavioral context: deletion only occurs when confirm=true, non-existent IDs are reported non-fatally, and a dry-run preview is returned otherwise. This explains the guarded nature 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the core behavior and then providing pairing advice. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key behavioral aspects (guarded deletion, dry-run, non-fatal missing IDs) and cross-references a sibling tool. While there is no output schema, the description implies return values for dry-run vs actual deletion, making it sufficiently complete for a cleanup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 67% schema description coverage, the schema already defines 'confirm' and 'tickets'. The description reinforces that tickets are exact IDs and confirm gates deletion, adding 'non-existent ids reported non-fatally', which provides context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Guarded cleanup: deletes ONLY the ticket ids you pass, and only when confirm is true (otherwise returns a dry-run preview).' It specifies the resource (tickets) and actions (delete or dry-run), distinguishing it from siblings like scan_board_cleanup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance by mentioning pairing with scan_board_cleanup's suggestedRemovals and explaining the dry-run vs actual deletion use. It implies the tool is for specific cleanup tasks, but 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond the neutral annotations: it specifies that the site is 'persisted through the website store and rendered to the site location', and explains the 'initGit' parameter behavior (git init and commit, returning the repo path). However, it does not mention potential side effects like overwriting an existing site, or any prerequisites. The annotations provide no hints, so the description carries the full burden, which it largely meets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences) and front-loaded with the primary action. Every sentence adds value: the first states the main purpose, the second explains persistence and location, the third details the 'initGit' option, and the fourth suggests pairing with another tool. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects) and lack of output schema, the description covers the core functionality well: it explains what is set, where it is stored, and a key optional behavior. However, it omits the output format (beyond 'repo path' for initGit) and does not mention error cases or prerequisites. It is sufficient for typical usage but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some meaning beyond the schema: it lists home page fields (title, tagline, theme, sections) and explains the 'initGit' parameter. However, with 57% schema description coverage, the description does not fully compensate for missing parameter descriptions (e.g., 'project' and 'tagline' lack schema docs and are not detailed in the description). The description maps to most parameters but does not explain format or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate a whole site in one shot from a single spec.' It specifies the verb ('Generate' or 'scaffold') and the resource ('a whole site'). It also distinguishes from the sibling tool 'set_site' by noting it works 'instead of set_site field-by-field.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with the alternative 'set_site' and recommends pairing with the 'generate_site prompt' to produce the spec. This provides clear guidance on when to use this tool (for bulk site creation from a spec) and mentions a complementary tool. No exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses numerous side effects not visible in annotations: writes to the work log, roll-up into velocity/metrics, pad snapshot refresh, owner stamping, ownership release, and uncommitted/commitReminder response behavior. It also clarifies failure semantics (mirror failure never blocks). This goes well beyond the annotations' basic non-read-only/non-destructive hints and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the information is all relevant, but the description is a single dense paragraph with long clauses and internal ticket references, making it harder to parse than its complexity warrants. It could be split into short labeled sections without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter tool with no output schema, the description covers the most decision-critical behaviors: gates, overrides, ownership conflicts, git/commit handling, and side effects. It leaves return-shape details mostly implicit, but it does mention compact ack vs full ticket view and the uncommitted warning, so an agent has enough to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 67% schema coverage, the description adds meaningful context for approve and force (gate overrides and takeover semantics) and explains why completion metadata (model, tokens, additions, deletions) matters by linking them to the work log and metrics. Several parameters like handoff and learnings are left to the schema, but the schema already documents them well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific, unambiguous action: 'Move a task between Todo / In Progress / Review / Done,' which names both the verb and the exact resource scope. It also adds workflow detail (Review gating) that distinguishes it from general update_task-style siblings. This is more than a vague restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete conditions for behavior—requireReview, requireCommitOnDone, graduated projects, git-enabled projects, and multi-user ownership—so an agent knows when gates or side effects apply. It does not explicitly name sibling alternatives or state when not to use set_status, but the context is clear enough to select it for status transitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false. The description adds important behavioral details: for 'commercial-trial' writes freeze after 24h, and 'commercial' requires a license key. This adds value beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using only a few sentences. It formats the enum options clearly with bullet-like structure and no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description covers all necessary aspects: what the tool does, what each option means, behavioral consequences, and prerequisites. Complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates by defining each enum choice (personal, public, commercial-trial, commercial) with their implications. This is essential for correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose ('Record how FeatureBoard is being used') and defines each enum value. It does not explicitly differentiate from sibling tools, but the mention of activate_license for commercial use indirectly distinguishes when to use that sibling instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to ask the user before setting, which guides appropriate use. For 'commercial' it directs to activate_license first, providing an alternative. No explicit 'when not to use' but the context implies when the user already has a license or trial ongoing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description confirms readOnlyHint annotation with 'Read-only — the server never edits code'. Adds that the output is a ready-to-execute proposal for Claude. Does not contradict annotations. Provides behavioral context beyond annotations by detailing output and execution responsibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. First sentence covers core functionality and output; second adds read-only note. No redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description adequately describes return content: symbols, modules, barrel guidance, prompt. References sibling tool for input. Does not cover error cases, but overall complete for typical usage. Could be slightly more explicit about prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (file parameter described, project not). Description mentions 'oversized source file' but does not explain the project parameter or provide parameter-level details beyond the schema. Lacks compensation for undocumented project parameter, resulting in inadequate guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool accepts an oversized source file and returns a structured refactor proposal. Distinguishes from siblings by being a read-only proposal generator that hands off execution to Claude. References code_file_map tool, differentiating it from other code tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for oversized files with splitCandidates from code_file_map. Clarifies that the server never edits code, so the tool is for proposing not executing. Implicitly tells not to use for direct edits. Provides clear context for integration with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotentHint=true, etc. The description adds valuable context: that verification is fully offline, that activation-by-order involves an outbound HTTPS POST, and that activation unblocks writes. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the purpose, then detail usage. Every sentence is informative without waste. The structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the tool's behavior well (modes, network call, offline verification, unlocking writes). It could mention the return value or status, but it's sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant meaning beyond the schema. It explains the two modes (key vs. email+orderId), when to omit each parameter, and the server's behavior in mode 2. This greatly aids correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it activates a commercial license and describes two modes. However, it does not explicitly distinguish this tool from related siblings like license_status or request_commercial_license, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides precise guidance: 'Activate a commercial license. Two modes — provide exactly one:' followed by detailed explanations of each mode. This tells the agent exactly when and how to use the tool, including conditions for each mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key side effects: carries fields, marks lead won, records company, errors if duplicate. Annotations show destructiveHint=false, so no destruction warning needed. Adds value beyond annotations by detailing what gets transformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences without redundancy. Each sentence adds distinct information: action, field mapping/options, and behavioral notes. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers inputs, transformation, side effects, and error condition. No output schema exists, but the description adequately explains the result (company created, lead updated). Could mention response structure, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description explains the meaning of fields (name, website→domain, notes summary) and the createContact parameter's role. It complements the schema by contextualizing how parameters map to lead fields, exceeding schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the specific verb 'convert' and resource 'lead to a company', detailing field carryover and optional contact creation. It distinguishes from sibling tools like 'add_lead' or 'set_lead_status' by focusing on conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for qualified leads and warns of errors if already converted, but does not explicitly state when not to use or provide alternatives. However, the context of sibling tools (e.g., enrich_lead) provides indirect guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by detailing the output (full file with one test() per behavior) and confirming read-only behavior. Annotations already indicate readOnlyHint: true, but the description enriches with specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, 1 required, no output schema, the description fully covers the tool's behavior, output format, and usage context. No critical omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, and the description adds meaning: 'module' as import specifier, 'prompt' as plain-English behaviors, 'ticket' as seed. It clarifies optionality and complementarity of prompt and ticket.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a FULL node:test file (path + content) from a prompt and/or a ticket', specifying the output format and distinguishing it from siblings like save_generated_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Read-only: returns the file for you to write under test/' and 'Optionally imports a target module', implying the tool is for generation only. It provides context for when to use, though alternatives like save_generated_test are not explicitly mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=true, and the description (listing templates) is consistent. It adds context about the types of templates available, but no additional behavioral traits are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded, no wasted words. Clearly conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters and no output schema, the description completely covers what the tool does and provides examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema (schema coverage 100%). No additional parameter meaning needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'available starter website templates' with examples ('landing, docs, blog'). It distinguishes from sibling tools like 'apply_site_template' and 'deploy_site'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used to see available templates. It doesn't explicitly mention when not to use it, but the sibling list provides context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses default compact view, pagination with limit/offset, and filtering behavior. Annotations already indicate read-only, which description reinforces.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that efficiently convey purpose, default behavior, filters, pagination, and an alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return format (compact vs full) and pagination. Covers filtering, ordering, and when to use an alternative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (27%). Description enumerates filterable fields (type, status, product, label, search) and explains compact and pagination, but does not detail each parameter's meaning or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists features and/or bugs on a board with most-recent-first ordering. Distinguishes from sibling tools like get_metrics and get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests using get_metrics for a pure overview, providing an alternative. Implicitly differentiates from other list tools by naming the resource and filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it's informational only, appends to audit log, and that the latest dispatch overwrites previous. Beyond annotations which only indicate non-readOnly and non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with key info front-loaded. Could be slightly more structured but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a logging tool with no output schema, description provides sufficient context: when to use, parameters, behavior. Lacks response format but probable simple acknowledgment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context for model (use when worker is sub-agent) and parallel (running alongside other dispatches). The schema covers 67% of parameters, and description fills in gaps for usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it records who is actively working a ticket as an audit event. It distinguishes from siblings like set_status and get_agent_monitor by focusing on the dispatch handoff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to call: right after set_status 'In Progress' for sub-agent handoffs and when taking back with orchestrator. Also states it never moves status and that the newest call wins.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: removes comment, cascading deletion by default, option to refuse if replies exist, and returns removed ids. Adds value beyond the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, followed by essential detail. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with annotations and no output schema, the description covers purpose, parameter behavior, and return value adequately. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context for the id parameter (source) and explanation of cascade parameter behavior. With schema coverage at 25%, description compensates by clarifying two out of four parameters. Could mention name and project but still helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Remove a comment by id' and specifies the source of the comment id from 'get_media / list_media_comments'. Distinguishes itself from siblings like add_media_comment and list_media_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context by explaining the default behavior of removing reply subtree and how to change it via cascade parameter. Doesn't explicitly list when not to use but is sufficient for a deletion tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=false, so the description is not required to restate safety. It adds value by disclosing that `threshold` (default 30) affects only summary wording, not which findings fire, and that `project` triggers extra rules from voiceProfile. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph covering purpose, usage, parameters, and behavioral details without redundancy. It could benefit from slight restructuring (e.g., separating parameter behavior), but every sentence provides essential information, and it remains brief given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (1 required), no output schema, and no enum constraints. The description explains the input role, parameter effects, and intended usage context (editing own drafts). It does not describe the exact return format, but deducing from context (scores/findings) is reasonable. The description is complete enough for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero description coverage for the three parameters. The description compensates by explaining `project` applies that project's voiceProfile config (extraBannedPhrases, allowedTells, samplesNote) and `threshold` only changes summary wording. For `text`, the description's context (scoring own drafts) clarifies its role. This adds meaningful semantics beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as scoring text for AI-writing tells, listing specific patterns (e.g., 'delve', contrastive-pivot rhetoric, sycophantic openers) and referencing a research-backed ruleset. The verb 'score text' plus the resource 'AI-writing-tell scorer' provide a specific, immediate purpose that distinguishes it from sibling tools like 'validate_feedback' or 'eval_report'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this tool is for editing 'YOUR OWN outbound drafts' and warns against using it to judge others' writing. It also explains when to pass the `project` parameter (to apply voiceProfile config) and states that `threshold` only changes summary wording, not which findings fire, providing clear guidance on use vs. non-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it uses cached git log/numstat, pagination with worst-drift first, and that totals cover all tickets. Annotations (readOnlyHint=true) are consistent. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Packed with information but not overly verbose. Each sentence adds unique value. Could be slightly better structured with bullet points, but efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return format (per-ticket drift, overall churnAccuracy) and pagination semantics. Complete for a reconciliation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds value beyond schema: explains limit/offset mirror list_tasks, driftThreshold filters but totals still cover all, full ignores pagination. Schema covers 80% of parameters; description compensates for the missing project description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it compares work log and git-actual numstat for Done tickets with tagged commits, reporting per-ticket and overall churn accuracy. This is specific and distinguishes from any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (Done tickets with tagged commits), pagination behavior (limit/offset, full flag), and drift threshold filtering. However, it does not explicitly exclude alternative tools or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotence and non-destructiveness. Description adds crucial details: refusal to create inside repo, reuse behavior, error conditions, and return items. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single paragraph that efficiently communicates purpose, caveat, behavior, and error conditions. Slightly long but every sentence is informative. Could be split for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description specifies return items (path, branch, guidance). Covers error conditions and corner cases (non-git path, old git, directory squatting). Complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 33% of parameters with descriptions (only baseRef). Description compensates by explaining defaults (baseRef from HEAD), branch naming convention, and worktree path pattern. Adds meaningful context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create (or reuse) an isolated git worktree for a ticket' with a clear verb and resource. It distinguishes from sibling tools like cleanup_worktree and list_worktrees by emphasizing parallel work on multiple tickets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (parallel ticket work) and includes a caveat about avoiding synced repos. Could improve by naming alternative tools like cleanup_worktree for removal, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavior: it creates subtasks linked to the parent, deletes the parent (unless keepParent is true), and returns new tickets. This aligns with annotations (destructiveHint: true) and provides additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three short sentences. The main purpose is stated first ('Replace one feature with a set of linked subtasks'), and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested subtasks, no output schema), the description covers the core action and return value. It lacks details on error cases or prerequisites, but is sufficient for a straightforward mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema description coverage is 50%, the description adds meaningful context: it explains that the subtasks parameter is user-provided and that the tool creates them. It also implies the role of the 'ticket' parameter as the parent. This compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: replacing a feature with linked subtasks. It uses specific verbs ('Replace', 'deletes') and resources ('feature', 'subtasks'). It distinguishes from siblings like add_feature or delete_task by focusing on decomposition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 break a feature into subtasks), but does not explicitly state when not to use it or mention alternatives. Context is clear, but lacks exclusions or guidance for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining that dismissals are append-only, future scans hide the finding and report dismissedCount, and the id is a stable hash. No contradiction with annotations (idempotentHint: true, destructiveHint: false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, well-structured with purpose, usage, and behavioral note. It is front-loaded and concise without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with no output schema, the description covers purpose, behavior, parameter details, and idempotency. It could mention error cases or return values, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (2 of 3 params have descriptions). The description enhances understanding by explaining the findingId is stable and shown in scans, and that reason is optional. It provides additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suppresses a scan_board_cleanup finding without deleting anything, intended for false positives or accepted risks. It uses specific verbs and resource, and distinguishes from sibling scan tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (false positives or accepted findings) and how it affects future scans. It does not explicitly mention alternatives or when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations. Annotations mark it as destructive (destructiveHint=true), and the description elaborates: 'file_bugs files a linked, drift-labeled bug per gap; reopen moves them back to Todo; relabel adds a drift label.' It also mentions dryRun for preview and that it records actions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences that first summarize, then enumerate actions, and finally add additional options. Every sentence adds value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 5 parameters, destructive nature, and lack of output schema, the description covers the purpose, actions, verdicts, dryRun, and recording behavior. It does not specify the return value (though no output schema is present) or prerequisites, but it is largely complete for an actionable remediation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema coverage, the description adds meaning to the action parameter by detailing each enum value, explains verdicts (default ['drift']), and clarifies dryRun. However, the project parameter, which is required, receives no explanation. Overall, the description compensates for most schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'One-click remediation across a run's flagged tickets' and lists the specific actions (file_bugs, reopen, relabel). This is a specific verb+resource combination that distinguishes it from sibling tools like drift_report, which only reports without applying changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (when you have flagged tickets and want to apply remediation) and describes the actions and dryRun option. However, it does not explicitly state when not to use it or compare to alternatives like drift_report, which would provide clearer guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return value (runId + tickets to score) and the two modes. Annotations are all false, providing no safety signals; the description compensates by explaining it initiates a run. Could be more explicit about side effects, but sufficient for a start action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and mode explanation. The embedded workflow adds length but is highly valuable. Every sentence contributes to understanding usage. Could be slightly more concise by separating workflow into a separate note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides necessary return info and a complete post-invocation workflow. It fits well within the sibling tool list and gives enough context for an agent to use it correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema coverage, the description adds significant meaning: clarifies that 'sample' mode uses a seeded random subset, seed is auto-generated if omitted, and sampleSize only applies to 'sample'. However, it does not describe the 'project' or 'type' parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a drift evaluation over Done tickets, distinguishing between 'sample' and 'full' modes. It differentiates from sibling tools like drift_record and drift_report by being the first step in a documented workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use 'sample' vs 'full' based on need for speed vs completeness. Provides a complete workflow after invocation: use get_work_packet, drift_record, then drift_report. Also suggests using the evaluate_drift prompt for the full loop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds context about HTML output and mcp_tools dependency, but could further clarify no side effects beyond safe read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds value, but description is relatively long. Could be tightened slightly, but front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, description covers all necessary context: purpose, usage, output handling, artifact lifecycle, and mcp_tools requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds no parameter info, which is acceptable given zero parameters and 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns the board UI as HTML document, explicitly linking to natural-language requests and distinguishing from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage examples, tells when to use (any board request) and when not to (hand-writing), and gives step-by-step instructions for output handling and artifact reuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this. The description goes beyond by detailing the exact filesystem signals included (dirty files, commits, worktrees, .fb-progress files), and explains behavior in all-projects mode (quiet projects returned as plain name strings). It also provides context about sub-agent conventions (e.g., .fb-progress file usage).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that is front-loaded with the purpose but then delves into detailed explanation of data content and usage. While every sentence adds value, the description is somewhat verbose and could be more concise. However, it is well-structured with the key information presented early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return shape: per repo information (dirty files, commits, worktrees, .fb-progress, recently-modified files, board-side signals). It also covers the all-projects mode and provides operational context about sub-agent conventions. The description is complete enough for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 4 parameters. The description adds marginal value beyond the schema: it mentions that omitting 'project' gives an all-projects rollup, which the schema implies. However, the description does not add detailed semantics beyond what is in the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is 'Read-only git/filesystem ground truth about what coding sub-agents are doing RIGHT NOW'. It specifies the resource (filesystem activity of sub-agents) and scope (one project or rollup across all projects). It distinguishes from siblings like get_agent_monitor by explaining that this tool provides filesystem-level data rather than board-level data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this for stalled-ticket triage (get_agent_monitor flags a stall from board events; this answers "but is anything actually moving?") and for a cross-project "what's live right now" rollup on Mission Control.' It also explains when not to use it: 'Sub-agents deliberately never write the board mid-flight... the board itself has nothing new to say — the filesystem is the only truth.' This provides clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: read-only, truncation with notice, omission of later commits when over cap, and warning instead of error for missing codeLocation or no matching commits. Annotations confirm readOnlyHint, and the description adds deeper context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and structured well, but it is somewhat verbose with extensive detail on the semantic parameter. Every sentence adds value, though some trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return values (per-commit summary, diff, truncation, warning) and handles edge cases (missing codeLocation, no commits). It covers all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema for parameters like maxBytes (truncation behavior) and semantic (details of the semantic view). For project and ticket, which lack schema descriptions, the context is implied but not explicitly defined. Overall, it provides useful additional semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures code changes for a ticket by finding commits mentioning the ticket id and returning per-commit summaries plus a diff. The verb 'get' and resource 'ticket diff' are explicit, and the scope (from project's code repo) uniquely distinguishes it from siblings like list_code_files or read_code_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when the tool is read-only and warns about truncation and non-error warnings, providing usage context. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, missing clear exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides thorough behavioral details beyond annotations: explains that pads stay in boards dir (read-only), exclusions (pad files, junk), git behavior with tolerance for absence/failure, and the dry-run default. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the main purpose and key details. However, it includes some tangential information (e.g., 'CADSolver was the manual prototype') that could be omitted. Overall, it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, destructive, no output schema), the description comprehensively covers the graduation process, exclusions, git handling, dry-run behavior, and pad outcomes. It provides enough context for an AI agent to use the tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% with descriptions for apply, commit, excludes, targetPath. The description adds value by explaining the overall workflow and how parameters interact (e.g., dry-run when apply=false, git behavior when commit=true). While not detailing individual parameters much, it compensates with process context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool graduates an incubator project to a dedicated repo by copying code, repointing codeLocation, setting stage=graduated, and recording the move. The lifecycle 'Option C' and the description of exclusions make the purpose specific and unambiguous. While it doesn't explicitly differentiate from siblings, the unique graduation action sets it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the dry-run default behavior and how to trigger actual execution (apply:true), guiding the agent on safe usage. It also mentions the lifecycle step ('Option C'). However, it lacks explicit when-not-to-use conditions or alternatives, which would be helpful for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present but the description adds critical context: the heartbeat is 'informational only and does not move the ticket’s status'. This transparency goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with front-loaded purpose and clear structure. A few minor redundancies exist (e.g., 'informational only' repeated), but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple logging tool, the description covers purpose, usage context, behavioral nuances, and examples. It fully explains the need for such a tool in the context of long dispatches and monitoring.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, so the schema documents most parameters. The description mentions optional parameters (model, elapsed minutes, tokens) but does not add new semantic detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'append' and resource 'in-flight progress ping', clearly distinguishing the tool from log_work. It states the purpose: to log a lightweight heartbeat during active dispatch for monitoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use (at natural milestones during long dispatches) and when not to use (not on every tool call). It contrasts with log_work, which is for completed work, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide non-destructive and open-world hints. The description adds rich behavioral details: uses gh CLI or falls back to a compare URL, conditionally pushes the branch (only when git mode is commit-push), and never throws errors (returns opened:false with reason). This far exceeds what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the main action and then layers conditions and guarantees. Every sentence adds value; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of an output schema, the description covers common scenarios (gh available, push needed, error handling) and explains when it returns a URL vs. opens directly. It could be slightly more explicit about the success return structure, but overall it's quite complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% with 'ticket' and 'project' lacking descriptions. The description adds meaning by explaining how ticket and project are used to form branch names and locate the repo, and how base and draft affect behavior. While not parameter-by-parameter, it compensates well for the gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Turn a ticket's pushed ticket/<id> branch into a pull request', using a specific verb and resource. It distinguishes itself from sibling tools like create_worktree and commit_feature by positioning as the last step in the worktree→review loop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly places the tool in a sequence ('after create_worktree + commit_feature') and explains fallback behavior when gh CLI is missing. It does not provide explicit when-not-to-use guidance but the context is strong enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond annotations: it specifies validation against build preflight rules, rejection of hard errors (missing name/description), and that only provided fields change. Annotations already indicate idempotence and non-destructive nature, so this is complementary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: one stating purpose and fields, another on validation and partial updates. It is front-loaded and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description covers key behavioral aspects (validation, partial update) but does not specify the return value or confirm whether it creates or updates. Still, it is adequate for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by listing all meaningful parameters (name, displayName, description, etc.) and their slugified nature. However, it omits the required 'project' parameter's meaning, relying on implicit context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool persists packaging metadata for a project, listing the fields it handles (name, displayName, etc.). It distinguishes itself from sibling tools like 'validate_packaging' which only validates without persisting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for updating packaging config, noting validation rules and partial updates. While it does not explicitly state when not to use alternatives, the context is clear enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'read-only deep-clean scan' and 'Never deletes'. It provides detailed behavioral context about what scans are performed (duplicates, staleness, missing labels, SLA breaches) 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is packed with information in two sentences, front-loaded with the core purpose. It could be slightly more concise but no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at the return value ('Returns a suggested removal set to feed prune_board') and explains all scanning categories. For a tool with 3 parameters and moderate complexity, it is complete and provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema describes 'staleDays' and 'similarity' with defaults and descriptions; 'project' is required but not described in schema. The description adds value by mentioning the 'slaThresholds config key' for overriding thresholds, which is not a parameter but related configuration. Schema coverage is 67%, and the description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'read-only deep-clean scan' that finds duplicate tickets, stale tickets, missing labels, and SLA breaches. It distinguishes itself from the sibling tool 'prune_board' which actually deletes, making its purpose specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it's a 'good fit for a recurring Cowork scheduled task' and explicitly states 'Never deletes', implying when to use it. It doesn't explicitly list when not to use it but the context makes it clear. Sibling tools like 'prune_board' are implied as alternatives for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that by stating 'Read-only' and 'Never deletes'. Beyond the annotations, it adds behavioral context: what types of files it finds and that it returns a suggested removal set, providing a clear behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences without redundancy. The first sentence packs key functionality with specific examples; the second adds return type and relationship to sibling tool. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, return type (suggested removal set), and relationship to the sibling. It lacks mention of prerequisites (e.g., project must exist) or potential error states, but these are minor given the tool's simplicity and the presence of a single required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'project' with no description (0% coverage). The description clarifies that the parameter identifies the project whose test directory is scanned, adding essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a read-only deep-clean of the project's test/ directory, enumerating specific file types it finds (duplicate, stale, empty stub). It distinguishes itself from the sibling scan_board_cleanup by explicitly stating it never deletes and is a companion tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it is a companion to scan_board_cleanup, implying a workflow where this scan identifies files for cleanup and the other tool likely performs deletion. However, it does not provide explicit when-not-to-use criteria or list alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses search scope (titles+content), ranking (title hits weighted higher), and output details (excerpt, path). Annotations already provide readOnlyHint, and description adds significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then results and context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return structure (matches, excerpt, path) despite no output schema. Relates to get_work_packet for additional context. Could detail pagination but adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers limit and query with descriptions (67%). The description adds value by linking 'project' to 'a board's kb doc', clarifying the required parameter's role. No further elaboration on limit or query beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states specific verb+resource: 'Keyword search across a board's kb doc titles + content, ranked'. It clearly differentiates from siblings like list_kb_docs and get_kb_doc by focusing on search. It also notes the relationship to get_work_packet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for searching kb docs by keyword and notes the same matcher used in get_work_packet, providing context. However, it does not explicitly state when not to use or compare to alternatives like rag_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false. Description adds context about no API key storage and env var sourcing. Shows it's a configuration mutation (not read-only) consistently 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. Front-loaded with primary purpose. Every sentence adds value: distinguishes from sibling, explains providers, and key security detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 1 required, and no output schema, description covers main aspects: purpose, sibling distinction, provider specifics, env var usage, and enable/disable. Lacks success/error details but sufficient for configuration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 63% (moderate). Description adds meaning: explains provider options (e.g., custom endpoint substitution), notes Google Analytics needs OAuth, and clarifies enabled false turns proxy off. Goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Configure', resource 'external analytics provider', and explicitly distinguishes from sibling 'set_site_analytics' which injects tracking. It specifies that this tool reads site traffic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (reading traffic) and when-not (injecting tracking) via distinction from set_site_analytics. Also gives provider-specific guidance (e.g., Google Analytics needs OAuth) and disabling via enabled:false.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses fire-and-forget nature, no blocking, CPU-bound, file output, and survival after call. Annotations already indicate non-readOnly, so description adds context like resource usage and persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured, front-loaded with core action. Slightly verbose but each sentence adds value. Could be trimmed slightly for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return value, failure case, file location, and polling mechanism. No output schema needed as descriptions handles it. Complete for a fire-and-forget tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description explains revision defaults and ticket association beyond schema descriptions. Project parameter not described in schema, but description implies its role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it spawns a detached background run of static checks on project's .js/.mjs/.cjs files and returns a runId. Distinguishes from sibling commit_feature which does automatic checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'use this to run them on demand' and notes commit_feature auto-starts checks. Also explains when it returns started:false (no config).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: uses deterministic keyword heuristics (no model calls), dry-run creates nothing, apply bulk-creates candidates, and allows passing an edited candidates array. It also mentions that the tool is idempotent in dry-run mode (but not in apply mode). This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with the core purpose and key behavior. It is slightly verbose but each sentence provides necessary information. The length is justified by the complexity of the tool's two-phase workflow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return value ('structured candidate list') and the two-phase process. It covers all important aspects: dry-run, apply, editing candidates, and the heuristic nature. No gaps in understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to parameters beyond the schema: explains that apply:false is the default and creates nothing, feedback is the raw text to parse, and candidates is an optional edited list for apply mode. It clarifies the workflow. However, the 'project' parameter lacks a schema description and the tool description does not elaborate on it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: parsing unstructured feedback into candidate tickets with a specific method (deterministic keyword heuristics). It uses a specific verb ('Parse') and resource ('unstructured feedback') and distinguishes from sibling tools by highlighting the bulk parsing from raw text and the two-phase dry-run/apply pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidelines: always dry-run first, then call with apply:true. It explains the default behavior and the workflow. However, it does not explicitly compare to sibling tools or state when not to use this tool (e.g., when feedback is already structured or when only one ticket is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: comments appear in get_work_packet.reviewComments, can send ticket back to next_task, and are recorded on audit history. Annotations are all false, so no contradiction; the description adds significant context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences provide all necessary information without redundancy. The first sentence states purpose, the second explains behavioral consequences, and the third mentions audit logging. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers input semantics, behavioral effects, and ties to other tools (get_work_packet, next_task). It is complete for an agent to understand when and why to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with some parameters described. The description adds context that the comment can be anchored to a file and line, and that it's PR-style review feedback. This adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'attach', the resource 'ticket', and the optional anchoring to file and line. It distinguishes from sibling tools like 'list_review_comments' and 'resolve_review_comment' by specifying the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that unresolved comments surface in the next work packet and, when ticket is in Review, send it back to queue. This provides clear context on when to use the tool. It does not explicitly state when not to use, but the usage is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool replaces site config and renders, adding detail beyond annotations (destructiveHint: true). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first covers action and effects, second gives after-use guidance. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity, description covers purpose, usage, behavioral effects, and refinement steps. Adequate for an AI agent to understand and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), but description adds context by listing what the tool sets (title, tagline, theme, sections, starter pages). However, it does not explain individual parameters like 'project' or the enum values beyond listing template types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Seed' or 'Start' the website from a starter template (landing, docs, blog). Distinguishes from siblings like set_site/add_page by noting them as refinement tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Replaces the current site config — use set_site/add_page to refine after', providing clear when-to-use and when-not-to-use guidance with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses multiple behavioral traits beyond annotations: refusal conditions, no-op behavior, safety check for unrecognized paths, and branch preservation. This aligns with and expands on the 'destructiveHint' and 'idempotentHint' annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding distinct value. The main action is front-loaded, and every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cleanup tool with destructive consequences, the description covers all critical aspects: primary action, refusal conditions, edge cases (no worktree, unrecognized path), and post-conditions (branch intact). No further context is needed given annotations and sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'force' parameter by linking it to uncommitted changes and safety. For 'project' and 'ticket', it provides context via example usage ('ticket/<ticket> branch'). With only 33% schema coverage, the description compensates adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('ticket's git worktree'), clearly distinguishing it from its sibling 'create_worktree'. It explicitly states the action and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use (after branch merge), when it refuses (uncommitted changes without force), and when it no-ops (no worktree registered). It lacks explicit alternatives but effectively sets usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-readOnly mutation (commit/push), details site location logic, git credential usage, and push resolution behavior. Goes well beyond annotations which only indicate open-world and non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds value; front-loaded with core purpose, then logically expands on location, prerequisites, and behavior. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, location, push behavior, and execution context (local git credentials). No output schema, but description is sufficient for correct invocation without missing info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant context for 'push' parameter (resolution rules) and 'project' (site location), but does not describe 'message'. Schema coverage 67% is partially compensated by description detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it re-renders and publishes the site via git commit/push, distinguishing it from other tools. References to 'MCP equivalent of old website deploy' and explicit verb+resource make purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies prerequisite (git integration enabled) and explains push behavior resolution. Does not explicitly contrast with sibling tools, but context is clear; no alternative deploy tool exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations providing only destructiveHint=false and readOnlyHint=false, the description gives extensive behavioral context: it works on a COPY in a temp dir (never touches the repo), seeds deterministic mutations, and writes nothing unless writeEvidence:true. It also mandates a mode field to prevent confusion between demo and real runs. This far exceeds the minimum transparency required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that packs a lot of information without excessive verbosity. It front-loads the core purpose and then details parameters and behavior. While dense, it remains readable and every sentence adds value. A minor improvement could be breaking into bullet points for easier scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects, no output schema), the description is remarkably complete. It covers the overall process, the return values (defects caught, unique-catch rate, overlap matrix, cost), edge cases (omit targetFile, writeEvidence), and the importance of the mode field. The description compensates for the lack of an output schema by describing the readout.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 86% schema coverage, the description still adds significant value. It explains that targetFile is required for mutations, the default built-in mutation set, how tokensByModel feeds into cost calculations, and that writeEvidence appends to docs/EVIDENCE.md. The mode parameter's enum values are explained, and the description clarifies the behavior when mutations or targetFile are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool evaluates per-model test variants against seeded regressions to determine defect-catching effectiveness. It specifies the file pattern (test/<ticket>.<model>.test.js), the use of copies in temp dirs, and the outputs (defects caught, unique-catch rate, overlap matrix, cost per caught defect). This distinguishes it from sibling tools like eval_report or generate_multi_model_tests by focusing on model comparison via seeded mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: to run test variants against regressions for model effectiveness. It distinguishes two modes ('real' vs 'harness-validation') and clarifies that omitting targetFile runs a baseline matrix. While it doesn't explicitly compare to alternatives like eval_report, the context signals show siblings are diverse and this tool is clearly specialized. The description provides sufficient guidance for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but the description adds significant behavioral context: the tool returns HTML that must be written to a file and used with create_artifact/update_artifact, and the mcp_tools array must be used verbatim to avoid allowlist errors. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and provides essential context, usage examples, and procedural instructions. It is slightly lengthy but each sentence adds value, making it effective without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and annotations covering read-only nature, the description is comprehensive. It explains the return type, artifact usage, MCP tool requirements, and related tools. Minor omission: no error handling details, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no parameter description is needed. Baseline score of 4 applies as there is nothing to explain beyond what the schema provides (schema_description_coverage=100%).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the Research RAG Explorer UI as a self-contained HTML document, ready to render as a Cowork artifact. It distinguishes this from hand-written explorers and relates to sibling tools like add_kb_doc, rag_search, and search_kb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage examples are given: 'show/open the RAG', 'what's in the knowledge base', 'let me query the research index'. Negative guidance is provided: 'Do NOT hand-write your own explorer'. Instructions for artifact handling are also included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds specific context about what information is reported (usage tier, writes allowed, trial time remaining), beyond the annotation's generic read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste, front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description fully specifies return contents (usage tier, writes allowed, trial time), which is sufficient for a simple status-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters and schema coverage is 100%, so description needs no parameter info. Baseline for no parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Report' and specific resource 'current licensing state' with three concrete fields (usage tier, writes allowed, trial time remaining). Distinguishes from sibling tools like activate_license or request_commercial_license.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this if a write was blocked, or during onboarding,' providing clear when-to-use guidance without needing to list when-not-to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses non-obvious behaviors: lanes containing a running ticket are never re-served, an empty wave is a steer_project event rather than a stop signal, and multi-user concurrency is handled via heldByOthers and heldBy lane withholding. None of this is visible in the schema or annotations, and it does not contradict the readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and each sentence adds a distinct fact about batching, lane discipline, or concurrency — no filler. It is a long unbroken paragraph (~200 words), so it is denser than ideal for scanning, but the complexity of the concurrency contract justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the essential output structure (lanes[], sequential[], busyLanes, heldByOthers, per-ticket dispatch blocks) and the full call/refill lifecycle, which is the hard part. Small gaps remain: the `type` filter behavior and `project` parameter are never tied to wave semantics, and the 'fable' label for sequential tickets is unexplained jargon.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 60% schema coverage, `maxLanes`, `laneDepth`, and `occupied` are already described structurally; the description enriches `occupied` with the refill semantics (exclude running tickets, withheld lanes come back under `busyLanes`) and ties `maxLanes` conceptually to lane concurrency. However, the required `project` parameter and the `type` filter receive no description-side context beyond their raw schema entries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'The PLURAL of next_task: return the whole dispatchable set at once' — a specific verb (return) and resource (the dispatchable set of tickets), and it names the sibling it extends, so an agent cannot confuse them. The title 'fill every lane' reinforces the batching purpose. This is a clear, distinctive purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs: 'Use this — not repeated next_task — whenever you are working a board with more than one open ticket,' giving the exact condition that selects this tool over its sibling. It also details the refill workflow (pass `occupied`, call again) and designates `stopCondition` as the authority on loop termination, so the agent knows when to stop calling and when to treat an empty wave as a steer_project event.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation: it states that tiers with fewer than minSamples get 'insufficient data' instead of a verdict, that includeRows can blow the result cap, and that the tool never writes model:/cap labels. These details fully disclose the tool's behavior and limitations, aligning with and enriching the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative, with a clear structure: the core question first, then data sources, metrics, cross-cutting by effort, caveats about insufficient data, read-only reassurance, sibling pairing, and return-value overview. Every sentence contributes meaningful detail without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, multiple metrics, conditional behavior) and no output schema, the description fully covers what the tool returns (per-tier and per-effort stats, opt-in rows), how it behaves with insufficient data, and the read-only nature. It provides a complete mental model for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 80% of parameters with descriptions, and the description adds practical meaning: it explains the minSamples threshold behavior, the includeRows opt-in and its result-cap impact, and the windowDays rationale ('older model generation is worse than none'). This goes beyond simple schema repetition, providing actionable guidance for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it scores every Done ticket from board data and reports per-tier metrics like cost per clean ticket. It distinguishes itself from siblings by explicitly mentioning pairing with plan_budget and daily_plan, and by framing its purpose as measuring actual performance rather than guessing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: for measuring which model tier actually runs tickets, and explicitly advises pairing it with plan_budget (what the queue will cost) and daily_plan (what to run today). It also notes the tool is 'advice only' and never writes labels, implying it is for analysis rather than action, but it does not explicitly state exclusions like 'do not use for modifying tiers'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits beyond annotations: commits changes, pushes conditionally, no-ops when disabled, mirrors pads for graduated projects, uses local git credentials, and auto-status on commit. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Somewhat lengthy but each sentence adds value. Front-loaded with primary action. Could be slightly more concise but remains clear and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations on complexity, the description covers all relevant context: conditions, behavioral nuances, parameter interactions, and edge cases like graduated projects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (3 of 6 params have descriptions). The description adds meaningful context for push, paths, and message params, and indirectly covers title/ticket format. Could be more explicit about required project and ticket format but overall helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool commits and optionally pushes changes with a specific message format. It distinguishes itself from siblings like open_pull_request by focusing on the commit action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (git enabled), when it's a no-op (disabled), how push behavior is resolved (gitMode or explicit), and when to use paths to avoid sweeping other changes. Also covers graduated projects mirroring.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: rejects over-limit copy, voice lint scoring (warn-only, never blocks), and that drafts are for user review. Annotations indicate write but non-destructive, and description adds important constraints beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. Front-loaded with main action. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers workflow (review via list_shares) and constraints (character limits, linting). No output schema, but description implies saved state with voice attachment. Slightly lacking return details but sufficient for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, but description clarifies each parameter: text as copy with length rules, platform as enum, asset as gallery item. Adds meaning beyond schema defaults for project and platform.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it saves a draft for a gallery item, never posts, and specifies platform-specific character limits. It distinguishes from sibling 'list_shares' by mentioning review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (save draft) and when not (no live-publish, never posts). Mentions alternative 'list_shares' for review. Provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description complements these by explaining the behavioral nuances of gitMode (e.g., 'ask' never pushes silently) and the planLimits blend tracking mechanics (FBMCPF-278/279), adding significant context about what the settings actually do. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It front-loads the core purpose and override note, then systematically covers gitMode and planLimits, ending with a practical instruction. No fluff, well-paced for the complexity involved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, including nested objects, the description covers the two most intricate parameters in depth. The other three are reasonably described in the schema, and there is no output schema requiring explanation. It is complete enough for an agent to call correctly, though it could briefly note that padSync, telemetry, and defaultStandard are also handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 60%, the description compensates for the two parameters lacking schema descriptions (gitMode and planLimits) by fully explaining their meaning and usage. The remaining parameters (padSync, telemetry, defaultStandard) already have descriptions in the schema, so the description does not need to repeat them. It adds value where needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Set', the resource 'FeatureBoard's account-wide settings', and the scope ('applied to every project that doesn't set its own override via set_git_config'), clearly distinguishing it from the sibling set_git_config. An agent can immediately understand what this tool does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative tool (set_git_config) and the condition for using each ('every project that doesn't set its own override'), and also instructs the agent to 'Ask the user about gitMode during onboarding'. This provides clear when‑to‑use direction and a concrete usage step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, which is consistent with the description's mention of claiming review candidates in steering.json. The description discloses important behaviors: it modifies state by claiming tickets, can report to user, and has a dryRun mode for previewing. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage. It contains detailed procedural steps. While every sentence adds value, it is somewhat verbose with numbered steps and parentheticals. Could be slightly more concise without losing key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains what the tool returns: 'ordered, executable passes' and the sequence of actions. It covers the full lifecycle, including failure condition and dryRun. For a complex steering tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (dryRun has a description, project does not). The description adds meaning: 'dryRun: true to preview without claiming' clarifies its preview behavior. Project is explained implicitly as the project to steer. While not exhaustive, the description compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'call this when next_task returns nothing (or the user asks to keep improving)'. It clearly identifies the tool as a steering mechanism that returns ordered passes. The sibling list includes next_task and next_wave, and this description uniquely distinguishes steer_project as the churn loop's answer to an empty queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'call this when next_task returns nothing (or the user asks to keep improving)'. Also explains the four-step process (REVIEW, TIGHTEN, RESEARCH, RESUME) and includes failure handling: 'If actionable is false twice in a row, report to the user and stop'. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only, zero tokens', consistent with the readOnlyHint annotation. It adds behavioral context: the first time a FAILED run is collected, it records a 'checks' audit event, which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it opens with the purpose, specifies priority of inputs, lists return fields, and ends with usage guidance. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists return fields (status, per-check results, ageSeconds) and explains the audit event. The 3 parameters are clearly explained through the precedence logic, making the tool's behavior fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only ticket has a description). The description compensates by explaining the precedence logic among runId, ticket, and project, adding meaning beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Collect the results of a background static-check run' and explains the priority of inputs ('by runId, else the newest run for a ticket, else the newest run overall'). It returns specific fields, distinguishing it from sibling tools like 'start_checks' and 'commit_feature'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it 'closes the async loop' after starting checks, advises collecting uncollected runs between tickets or before ending the session, and explains implications of a failed run ('fix it now or file a bug').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the idempotentHint annotation by explaining the REPLACES behavior, 'no appended contradictions', git history preservation, and frontmatter provenance accumulation. It fully discloses side effects and the canonical-replacement model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with purpose and an example. Every sentence earns its place, covering purpose, behavior, exclusions, and downstream effects in a single well-structured paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, exact file path (kb/learning-<slug>.md), replacement semantics, versioning, provenance, and indexing. Although there is no output schema, the return behavior is not critical for a write-oriented tool; the description gives the agent everything needed to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes topic, ticket, and content (75% coverage). The description adds meaningful semantics: topic as canonical key for updates, content as current complete truth that replaces wholesale, and ticket as provenance. The project parameter is not described in either, but it is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Record a durable, re-usable truth discovered while working' and names concrete examples (API gotcha, invariant, constraint). It explicitly distinguishes itself from sibling tools by saying 'not work narration (that's log_work) and not in-flight research (that's append_research)'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('knowledge the NEXT ticket needs') and explicitly names alternatives with their purposes. It also explains that learnings are indexed and auto-injected into work packets, giving the agent clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses deliberate outbound egress, no usage telemetry, no-op on empty/malformed, and safe to call again (idempotent). Annotations confirm idempotentHint and destructiveHint, with no contradiction. Description adds behavioral nuance beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is fairly long but every sentence adds value. It is front-loaded with the core action and structured logically. Slight verbosity prevents a 5, but it remains efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With low complexity and no output schema, the description covers all necessary aspects: behavior, side effects, edge cases (no-op, safe re-call), and contrasts with siblings. It is fully complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'email' has 100% schema coverage and description adds meaningful guidance: 'explicitly typed and submitted', 'omit/empty to skip'. This clarifies the parameter's role beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action: store an email from the tier-picker onboarding screen and POST it to a listener. It distinguishes from sibling tools by contrasting with notify_slack, which requires user-configured destination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (explicit submit), when not to use (speculatively, on render, with unconfirmed/autofilled value), and provides alternative behavior (skip via empty string). Contrasts with notify_slack for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint: true and destructiveHint: false, implying non-destructive idempotent behavior. The description goes far beyond by disclosing locking semantics, refusal to change without force, injection into work packets, and effects on research-on-intake. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-organized, front-loading the core action. It includes necessary inference rules and locking behavior. Slightly verbose but earns its length due to complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, locking, inference, side effects on packets and research), the description covers all essential aspects. It explains output behavior (injection into packets) and references global defaults, ensuring an agent can correctly invoke it without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 60% description coverage (force, source, mandate have descriptions; level and project lack them). The description compensates by explaining level values in detail (effect on ceremony, research, rigor) and clarifying mandate as free-text bar. It adds meaning beyond schema, especially for the enum parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to set and lock the rigor level of a project. It enumerates three levels ('prototype', 'standard', 'polished') with behavioral implications, distinguishing itself from other project settings tools like 'steer_project' or 'set_project_config' by emphasizing locking and inference rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use the tool (set the standard), when not to (when locked without force), and how to handle inference (infer once and lock). It also mentions account-wide default via set_global_config, offering complete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false. The description explains the idempotent behavior: 'Calling again with the SAME title updates in place.' It also discloses extraction behavior from path/url, auto-detection of title/source, and the needText response for problematic inputs. No contradictions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 6 sentences, well-structured with a clear opening, then methods in priority order, edge case handling, and sibling differentiation. No fluff—every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and moderate complexity, the description covers input methods, auto-detection, update behavior, RAG indexing, and error returns (needsText). It fully prepares the agent for correct invocation without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite high schema coverage (88%), the description adds significant meaning: priority order of parameters, auto-detection logic for title and source from url/path, slugification of title, and update behavior. It explains that passing title/source overrides auto-detection and that tags are topical. These details go beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save' and resource 'research source', specifies it goes into a board's sources/library, and explicitly distinguishes from sibling tools 'add_kb_doc' and 'append_research' by saying 'Use this for the sources; use add_kb_doc / append_research for YOUR notes about them.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on the three input methods in priority order (path, url, text), explains when to use which, and tells how to handle scanned PDFs or JS-rendered pages. It also clearly states when to use alternative tools for notes about sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by detailing observable behavior: status output fields, push commit-and-retry semantics, pull rebase behavior, rate-limit bypass for pull, auto-sync behavior, and monorepo handling. This substantially enriches the sparse annotation set and gives an agent a reliable model of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: the first sentence explains the three actions, the second provides usage context and selection criteria, and the third covers an important edge case. It is front-loaded and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers action semantics, when to use it, what status reports, push/pull failure behavior, rate-limit effects, and monorepo safety. Nothing essential for an agent to select and invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, but the description compensates by explaining each enum value of 'action' in behavioral terms and clarifying that 'project' is required for pull while status/push cover all pad repos. It adds meaning beyond the bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('Explicitly sync the board's pad repo(s)') and then enumerates the exact actions (status, push, pull). It clearly distinguishes this tool from generic git configuration or commit tools by scoping it to pad repos and manual sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is unnecessary ('Automatic syncing normally makes this unnecessary') and when it should be used: to verify sync state, force a flush before ending a session, or recover after being offline. This is direct guidance about when to invoke the tool relative to the automatic-sync alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![featureboard-mcp MCP server](https://glama.ai/mcp/servers/valentil/featureboard-mcp/badges/card.svg)](https://glama.ai/mcp/servers/valentil/featureboard-mcp)

Score Badge

Copy to your README.md:

[![featureboard-mcp MCP server](https://glama.ai/mcp/servers/valentil/featureboard-mcp/badges/score.svg)](https://glama.ai/mcp/servers/valentil/featureboard-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/valentil/featureboard-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server