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

Beyond the annotations (which indicate non-readonly, non-destructive, non-idempotent), the description adds critical behavioral details: content and data are preserved, the announcement can be unarchived later, and errors occur if already archived or if the ID is invalid. This fully informs the agent about side effects and failure modes.

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

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

The description is well-structured with clear sections (Args, Returns, Use Cases, Notes, Error Handling). The first sentence immediately conveys the core purpose, and every subsequent sentence adds value without redundancy. It is concise yet comprehensive.

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

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

Given the tool's simplicity (1 parameter, no output schema) and the presence of annotations, the description covers all necessary aspects: purpose, parameter, use cases, behavioral notes, and error handling. A minor improvement would be to include a more detailed return value example, but the current description is sufficient for selection and invocation.

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

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

The input schema has 100% description coverage for the single parameter 'announcement_id', matching the description text. Therefore, the description adds no new semantic meaning beyond what is already in the schema, resulting in the baseline score of 3.

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

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

The description clearly states the action ('Archive an announcement'), the resource ('announcement'), and the effect ('removing it from the active list while preserving its content'). It also distinguishes from deletion, a sibling action, by noting that archiving is reversible.

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

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

The description provides explicit use cases (e.g., 'Archive old announcement abc123') and notes that archiving differs from deletion. However, it does not explicitly contrast with other sibling tools like 'update_announcement' or 'publish_announcement', leaving some room for interpretation about when exactly to use this tool instead.

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

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

Discloses draft state creation, content format precedence, and error responses. Annotations already indicate non-destructive mutation, but description adds useful behavioral details.

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

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

Well-structured with clear sections: purpose, args, note, returns, use cases, error handling. No extraneous information.

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

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

Though no output schema, description specifies return fields (ID, headline, state, timestamp). Missing pagination or performance notes, but adequate for this tool.

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

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

Schema covers all parameters (100% coverage). Description adds important constraint: provide only ONE content format with explicit precedence order, which is beyond schema.

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

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

Clearly states 'Create a new draft announcement in a LaunchNotes project.' Specific verb+resource, and distinguishes from siblings like publish, archive, update, etc.

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

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

Provides use cases and error handling. Mentions content format precedence, but does not explicitly state when not to use this tool vs. alternatives like update_announcement.

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

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

The description adds significant behavioral context beyond annotations, notably that the mutation does not echo back a link ID and that read-back is unsupported. It also details error handling (validation errors, authentication failure). This aligns with annotations (readOnlyHint=false, 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.

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

The description is well-structured with clear sections (main description, args, returns, notes, use cases, error handling). It is front-loaded with purpose. A bit lengthy but every section earns its place, and it is not overly verbose.

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

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

Given no output schema, the description explains returns (success confirmation or validation errors) and covers error handling. It also notes the limitation about link ID. For a simple mutation tool with 3 required parameters, this is complete and transparent.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats parameter info but adds context like 'must include https://' for URL and ties parameters to the drafting flow (e.g., owner_id is announcement ID). This adds value beyond the schema.

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

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

The description clearly states it attaches a supporting link to a LaunchNotes announcement. The verb 'attach' and resource 'link' are specific, and the tool is distinguished from siblings like 'create_announcement' or 'update_announcement' by its unique purpose.

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

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

The description explicitly says it's designed for the drafting flow and provides use cases. While it doesn't mention when not to use it, it gives clear context for when to use it, e.g., after creating an announcement. It lacks explicit exclusion of alternatives but is still helpful.

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

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

Annotations indicate it's a write, non-destructive, non-idempotent operation with open world. The description adds significant behavioral context: creation semantics, required parameters, return structure, and detailed error handling including auth requirements (Management token). 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.

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

The description is well-structured with a clear intro, bulleted args, returns, use cases, and error handling. It is front-loaded with purpose and every sentence adds value without fluff.

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

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

For a creation tool with 5 parameters and no output schema, the description completely covers return values (ID, name, stage ID, timestamp) and error cases, making it self-sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats parameter names and types but adds no new semantic information beyond what the schema already provides, such as constraints or formats.

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

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

The description clearly states it creates a new work item on the LaunchNotes roadmap, explaining that work items are features/initiatives added to a specific stage. It distinguishes itself from sibling tools like list_work_items and move_work_item through its creation focus.

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

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

The description provides explicit use cases and error handling that indicate when to use the tool, but does not explicitly state when not to use it or direct to alternative tools for other operations.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds value by specifying error handling (return messages for not found and auth failure) and stating it returns 'complete details with all fields'. No contradiction with annotations.

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

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

The description is well-structured with sections for purpose, args, returns, use cases, and error handling. It is moderately concise, though some redundancy exists (e.g., 'complete details with all fields' in Returns).

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

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

For a simple retrieval tool with no output schema, the description covers input, purpose, and error responses. It mentions 'complete details with all fields' but could specify key fields (e.g., title, content). Annotations cover safety. Overall adequate but not exhaustive.

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

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

Schema description coverage is 100% and both parameters have detailed descriptions. The description largely repeats schema info ('output format' and 'announcement_id'). Since baseline is 3 for high coverage, the added value is minimal.

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

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

The description clearly states the verb 'Retrieve' and the resource 'announcement', specifying 'complete details including content, categories, and metadata'. This distinguishes it from sibling tools like 'launchnotes_list_announcements' (list) and 'launchnotes_get_top_announcements' (only top announcements).

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

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

The description provides explicit use cases and natural language examples, guiding when to invoke the tool. However, it does not explicitly state when not to use it or compare it to alternatives like 'launchnotes_list_announcements' or 'launchnotes_get_top_announcements'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by detailing return fields (content, notes, sentiment, customer info, associations, timestamps) and error messages ('Feedback not found', 'Authentication failed'), confirming safe read behavior.

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

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

Concise and well-structured with clear sections (summary, Args, Returns, Use Cases, Error Handling). Each section adds value without redundancy. Front-loaded with purpose.

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

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

For a simple retrieval tool with two parameters, schema covers all, annotations are rich, and description covers purpose, parameters, return values, usage examples, and error handling. No output schema needed as return content is explained. Complete and self-contained.

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

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

Schema coverage is 100% with both parameters described in JSON schema. Description's 'Args' section adds minor clarity but largely repeats schema information. Baseline of 3 is appropriate as description does not significantly augment parameter understanding beyond schema.

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

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

Description explicitly states 'Retrieve complete details for a specific feedback item' with specific verb and resource. It distinguishes from sibling 'launchnotes_search_feedback' by focusing on single item retrieval. Provides details on what is included (customer info, reporter, associations).

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

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

Provides concrete use cases like 'Show me details for feedback #abc123' indicating when to use. Error handling hints at invalid ID. However, it lacks explicit when-not-to-use or direct comparison with alternative sibling tools.

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

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

Annotations already indicate this is a safe read operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds useful behavioral context beyond annotations by specifying the return formats (JSON and Markdown) and error messages, enhancing the agent's 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.

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

The description is well-structured with clear sections (Args, Returns, Use Cases, Error Handling). It is front-loaded with the main purpose and is concise, including only necessary information.

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

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

Despite having no output schema, the description comprehensively covers both return formats and error cases. The tool is simple, and the description fully explains what the agent can expect, making it complete for a retrieval operation.

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

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

Schema coverage is 100%. The description repeats parameter info and adds default for response_format and example use cases, but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves complete details for a LaunchNotes project, including customization settings, colors, custom code, and feature flags. This distinguishes it from siblings like 'launchnotes_list_projects' which lists projects, and 'launchnotes_get_announcement' which retrieves a different resource.

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

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

The description provides helpful example use cases and error handling but does not explicitly state when to use this tool versus alternatives. For instance, it could mention that for listing all projects one should use 'launchnotes_list_projects'. No exclusion guidance is given.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds details on cumulative analytics, error messages, and return structure, which complement the annotations well.

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

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

The description is well-structured with sections, front-loaded purpose, and no wasted words. It repeats some parameter details from schema, but the overall clarity justifies moderate length.

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

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

For a read-only list tool with 4 parameters and no output schema, the description thoroughly covers error handling, return content, metrics, and usage examples, making it fully informative.

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

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

Schema coverage is 100%, so baseline is 3. The description provides additional context for metric enum values (e.g., 'most comprehensive') and clarifies response format differences, adding value beyond the schema.

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

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

The description clearly states it retrieves top-performing announcements ranked by various metrics. It distinguishes from siblings like list_announcements by focusing on ranking, and includes specific use cases.

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

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

Use cases are provided, and error handling guides when the tool might fail. However, it does not explicitly compare to similar tools like list_announcements, which would clarify when to choose this over siblings.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description correctly reinforces a safe read operation. It adds value by documenting default ordering (updatedAt descending), output format options (markdown default), and error handling (project not found, authentication failed). 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.

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

The description is well-structured with clear sections (Args, Returns, Use Cases, Note, Error Handling). It is concise, with every sentence adding value—no redundancy, no fluff. Ideal length for a parameter-heavy tool.

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

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

Given 6 parameters, no output schema, and no nested objects, the description covers all essential aspects: input parameters (with constraints and defaults), output structure (id, headline, state, dates, slug), ordering behavior, error cases, and use cases. It leaves no gaps for proper invocation.

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

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

Input schema has 100% coverage with detailed descriptions for each parameter. The description restates some schema info (e.g., 'limit' max 100, default 50) and adds a note on ordering dependency. However, it does not add substantial new meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states 'List all announcements in a LaunchNotes project with optional filtering and ordering.' The verb 'list' and resource 'announcements' are specific, and the scope (project-level, filtered) distinguishes it from siblings like 'get_announcement' (single item) or 'list_projects' (different resource).

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

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

The description provides explicit use cases (e.g., 'List all published announcements ordered by published date') and a critical note that both order_by_field and order_by_direction must be specified together. It lacks explicit guidance on when not to use this tool versus alternatives like get_announcement, but the use cases and sibling list imply its role.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds that it returns a list with id, name, slug, and public URL, and handles authentication errors. This adds 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.

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

The description is concise with clearly separated sections for args, returns, use cases, and error handling. Every sentence adds value, and it is front-loaded with the main purpose.

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

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

Despite lacking an output schema, the description explains the return structure (list with id, name, slug, public URL) and covers error handling. It is complete for a simple list tool with one optional parameter.

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

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

The schema already provides a description for the single parameter 'response_format' with enum and default. The description restates the same information. Since schema coverage is 100%, the baseline is 3; the description does not add significant new meaning.

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

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

The description clearly states 'List all LaunchNotes projects accessible with the current API token.' It specifies the verb (list), resource (projects), and scope (accessible with token). It distinguishes from siblings like 'launchnotes_get_project' which retrieves a single project.

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

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

The description provides concrete use cases such as 'Show me all my LaunchNotes projects' and 'List projects in my organization,' which guide when to use the tool. It does not explicitly mention when not to use or provide alternatives, but the use cases are sufficient.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. The description adds substantial behavioral context: returns a list with id, name, position; up to 100 stages; error cases (project not found, authentication failed). 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.

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

Well-structured: one-line purpose, then bullet lists for args, returns, use cases, error handling. Every sentence adds value. No fluff.

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

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

No output schema, so description must cover return values. It does: list of stages with id, name, position, max 100 stages, plus error cases. Comprehensive for a list tool.

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

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

Schema coverage is 100% with both parameters described. The description adds minimal extra value (e.g., default for response_format is already in schema). The use case note is helpful but not essential.

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

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

The description explicitly states 'List the roadmap stages for a LaunchNotes project, in their on-roadmap order.' This is a specific verb+resource, and the tool is clearly differentiated from siblings like list_work_items or list_announcements.

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

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

The description provides clear guidance: 'Use this to discover the target_stage_id parameter accepted by launchnotes_move_work_item.' It also lists explicit use cases such as finding the 'Shipped' stage ID. While it doesn't mention when not to use it, the context is strong enough.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds beyond: archived templates are excluded, return format details, sorting order, and error messages ('Project not found', 'Authentication failed'). No contradiction with annotations.

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

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

Well-structured with clear sections (description, args, returns, use cases, error handling). Every sentence is meaningful and front-loaded with the primary purpose. No wasted words.

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

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

Despite no output schema, the description fully explains the return value (id, name, headline, description) and error cases. It covers sorting, exclusion of archived templates, and parameter defaults. Complete for a list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by restating parameters with their purpose, including the effect of 'limit' and the allowed values for 'response_format'. This adds value beyond the schema.

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

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

The description clearly states the verb 'List' and resource 'announcement templates' for a LaunchNotes project, with explicit sorting and purpose. It distinguishes from siblings like 'launchnotes_list_announcements' by focusing solely on templates.

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

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

Provides explicit use cases and explains how the tool feeds into 'launchnotes_create_announcement'. However, it does not explicitly state when not to use it or compare with alternatives, though the context makes the purpose clear.

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

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

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by specifying return fields (id, name, stage_id, position), a 100-item limit, exclusion of archived items, and error handling messages. 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.

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

The description is concise yet comprehensive: a single-sentence purpose, followed by structured sections for arguments, returns, use cases, and error handling. It is front-loaded with the core purpose, 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.

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

For a simple list tool with 3 parameters and read-only behavior, the description covers purpose, usage context, return format, limits, and error scenarios. With strong annotations, it provides sufficient information for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with descriptions for each parameter in the JSON schema. The description's 'Args' section largely restates the schema, adding no new parameter semantics beyond the schema. It does provide the default for response_format, which is already in schema. Baseline 3 is appropriate as description adds minimal extra parameter meaning.

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

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

The description clearly states 'List the non-archived work items on a LaunchNotes project's roadmap, optionally filtered to a single stage.' This uses a specific verb and resource, and distinguishes from sibling tools like 'launchnotes_move_work_item' by highlighting its role in discovering work_item_id.

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

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

The description explicitly explains that the tool is used to discover work_item_ids for 'launchnotes_move_work_item' and notes that archived items are excluded. It provides clear context for use, though it does not explicitly state when not to use it.

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

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

Beyond annotations indicating mutation, the description discloses that no subscriber notification is sent, the item is appended to the bottom of the target stage, and details error handling for invalid IDs or authentication. No contradiction with annotations.

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

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

The description is well-structured with clear sections: purpose, what it doesn't do, arguments, return, use cases, and error handling. It is front-loaded and every sentence adds value.

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

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

Given only two simple parameters and no output schema, the description fully explains the return value (confirmation with names) and error handling. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description repeats those but adds valuable context by telling how to obtain the IDs via list_work_items and list_stages, and includes use cases, adding meaning beyond the schema.

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

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

The description clearly states 'Move a work item between roadmap stages,' using a specific verb and resource. It distinguishes this tool from siblings like create_work_item or list_work_items by focusing on moving an item between stages.

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

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

The description provides explicit guidance: use list_work_items and list_stages to discover IDs, gives example use cases like 'Move the auth feature to Shipped,' and clarifies that it does not send notifications (a separate operation).

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

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

Annotations already indicate mutating (readOnlyHint=false) and non-destructive. Description adds that subscribers are notified, errors for already published or not found, and authentication requirements.

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

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

Structured into clear sections (Args, Returns, Use Cases, Notes, Error Handling). Slightly verbose but all sentences add value. Front-loaded with core purpose.

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

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

Covers purpose, usage, preconditions, errors, and return value. No output schema, but description explains confirmation. Complete for a simple publish action.

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

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

Only one parameter 'announcement_id' with full schema coverage (100%). Description repeats basic info but error handling provides context beyond schema. Baseline of 3 applies as schema does the heavy lifting.

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

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

Clearly states 'Publish an announcement immediately, making it live and visible to subscribers.' Uses specific verb 'publish' and resource 'announcement'. Distinguishes from sibling tools like 'schedule_announcement' via notes.

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

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

Provides explicit use cases and preconditions (announcement must be draft/scheduled). Includes error handling for invalid states. Names alternative tool 'schedule_announcement' for future publishing.

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

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

The annotations are minimal (no hints for destructive, readOnly, idempotent). The description adds significant behavioral context: announcement auto-publishes, subscribers are notified, rescheduling is possible by calling again, and specific error conditions (past date, invalid format, not found). This greatly enhances 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.

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

The description is well-structured into clear sections (Args, Returns, Use Cases, Examples, Notes, Error Handling). It is front-loaded with the main purpose. However, it could be slightly more concise (e.g., the Notes and Error Handling are partly redundant with the schema). Still, it is effective and easy to read.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all essential aspects: what it does, parameter details with examples, return confirmation, use cases, and error handling. It provides enough context for an AI 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.

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing ISO 8601 format examples, explaining the default timezone, and giving practical usage examples. This extra context justifies a score above baseline.

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

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

The description clearly states the action ('Schedule an announcement to be published automatically at a specific future date and time'), uses a specific verb ('schedule') and resource ('announcement'), and distinguishes from sibling tools like 'publish_announcement' (immediate) and 'update_announcement' (edit). The inclusion of use cases further clarifies its purpose.

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

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

The description provides clear context for when to use the tool (scheduling future announcements) and includes examples of scheduled_at format. It implicitly differentiates from publishing immediately, but does not explicitly mention when not to use it or name alternatives. The sibling tool list provides additional differentiation.

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

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

The description adds error handling details ('Project not found', 'Authentication failed') and return structure, which supplement the annotations (readOnlyHint, destructiveHint). The annotations already indicate safe read-only behavior, so the description provides meaningful but not essential extra context.

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

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

The description is well-structured into Args, Returns, Use Cases, and Error Handling sections. It is front-loaded with the core purpose, and every sentence provides clear, non-redundant information. There is no wasted text.

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

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

Given the tool has 9 parameters, no output schema, and moderate complexity, the description covers all essential aspects: purpose, all parameters, return format, use cases, and error handling. It provides enough context for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description's Args section mostly mirrors the schema, though it adds default values (limit default 20) and output format options. This adds marginal clarity beyond the structured schema, meeting the baseline without exceeding it.

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

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

The description explicitly states 'Search and filter customer feedback in a LaunchNotes project' with a clear verb and resource. The use cases (e.g., 'What are customers saying about Digests?') further solidify the purpose, distinguishing it from sibling tools like `launchnotes_get_feedback` which retrieves a single item.

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

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

The description includes a 'Use Cases' section with practical examples (e.g., 'Show me all unhappy feedback'), indicating appropriate contexts. However, it does not explicitly state when not to use this tool or mention alternative tools, leaving some ambiguity for agents unfamiliar with the sibling set.

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

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

Annotations already indicate non-readonly, non-destructive, non-idempotent. Description adds important behaviors: requires at least one field, unchanged fields remain, and error handling details. 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.

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

Well-organized into Args, Note, Returns, Use Cases, Error Handling. Each sentence adds value; no redundancy or filler.

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

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

Covers all necessary aspects for an update tool: parameter details, usage notes, return value, error scenarios. No output schema needed given the description of return.

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

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

Input schema has no properties, so description carries full burden. It documents all parameters with types and optionality, and explains the special 'content' format requirement.

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

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

The description clearly states 'Update an existing announcement's content, metadata, or categorization.' It lists specific updatable fields and distinguishes from create and archive tools.

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

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

Provides clear context for when to use, including note about content format and reference to create_announcement for Markdown. Lists use cases but lacks explicit 'when not to use' statement.

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

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

Annotations indicate mutable, non-destructive, non-idempotent, and partial updates. The description adds context by stating unprovided fields remain unchanged and details error handling for invalid hex and missing project ID.

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

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

The description is structured into sections (general description, Args, returns, use cases, error handling) and is front-loaded with the purpose. Could be slightly more concise but well-organized.

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

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

Given many optional parameters and no output schema, the description covers required inputs, behavior (unchanged fields), error cases, and includes examples. Reasonably complete for a configuration update tool.

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

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

The input schema is empty, so the description carries full burden. It lists all 11 parameters with types, optionality, and format requirements (hex), adding significant value beyond the schema.

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

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

The description clearly states 'Update color palette and theme for a LaunchNotes project' with specific verb and resource. Use cases reinforce the purpose and differentiate from siblings like update_project_content.

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

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

The description provides some usage context through use cases and notes that at least one color field must be provided, but it 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.

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

Annotations indicate a non-read, non-destructive, non-idempotent operation. The description confirms mutation ('update') and adds error handling details (slug validation, project not found). No contradiction with annotations. It lacks details on side effects or permissions, but the error info helps.

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

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

The description is well-structured with Args, Use Cases, and Error Handling sections. It is slightly long but every section adds value. Could be more concise, but remains efficient.

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

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

Despite no output schema, the description covers return value (confirmation with updated fields) and error cases. It explains optionality and prerequisites (at least one field). For a tool with multiple parameters, it is sufficiently complete.

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

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

The input schema is empty, so the description carries full weight. It defines each parameter (project_id, name, title, description, heading, subheading, slug) with types and optionality, adding meaning beyond schema. This fully compensates for the lack of schema properties.

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

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

The description explicitly states 'Update project title, description, headings, and slug for a LaunchNotes project.' It uses a specific verb (update) and resource (project content), clearly distinguishing it from sibling tools like update_project_colors or update_project_features.

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

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

The description provides use cases ('Update project title to...', 'Change the heading and subheading') and notes that at least one content field is required. It does not explicitly exclude scenarios or mention alternatives, but the context is sufficient for an agent to infer when 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.

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

The description adds behavioral context beyond annotations, such as 'Fields not provided will remain unchanged', return of a confirmation with timestamp, and error handling scenarios. Annotations provide readOnlyHint=false and destructiveHint=false, which the description supports 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.

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

The description is well-structured with a clear function statement, bulleted args, usage rule, return info, use cases, and error handling. It is front-loaded with purpose, though the use cases list adds some verbosity.

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

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

Given the complexity of updating multiple optional fields, the description covers purpose, parameters, usage rules, return information, and error handling. It lacks an output schema but provides sufficient return details for simple use.

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

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

Despite the input schema being empty, the description lists all parameters with types and optionality, adding meaning beyond the schema. It includes examples and the requirement that at least one field must be provided, which compensates for the schema's lack of parameter definitions.

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

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

The description explicitly states the verb 'Update' and resource 'custom CSS, HTML head, header, footer, or index hero for a LaunchNotes project', clearly distinguishing it from sibling tools like 'update_project_colors' or 'update_project_content'.

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

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

The description provides clear context on when to use this tool (for custom code fields) and includes use cases and rules like 'at least one field must be provided'. However, it does not explicitly state when not to use it relative to alternatives.

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

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

Annotations indicate readOnlyHint=false, so the description correctly notes mutation. It adds that unspecified features remain unchanged and that at least one toggle is required, which are important behavioral constraints not captured by 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.

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

The description is well-structured with sections for Args, Returns, Use Cases, and Error Handling. It is front-loaded with the main purpose. Slightly verbose but every section adds value.

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

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

Given the empty schema and no output schema, the description provides ample context: parameter docs, error handling, use cases, and return type (confirmation message). It lacks details on the response structure, but overall it is sufficiently complete for an agent.

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

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

The description provides detailed parameter names, types, and optionality for 6 parameters, which adds value beyond the empty input schema (0 properties). However, the schema contradiction (schema has no params while description lists many) lowers the score. Schema description coverage is technically 100% but misleading.

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

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

The description clearly states the tool's purpose: 'Enable or disable features for a LaunchNotes project' and lists specific toggles (feedback, roadmap, etc.). This verb+resource+scope formulation effectively distinguishes it from sibling tools like update_project_colors or update_project_content.

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

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

The description provides explicit use cases (e.g., 'Enable feedback collection for my project') and notes that at least one feature toggle must be provided. It does not explicitly state when not to use this tool versus alternatives, but the context of sibling tools makes the purpose clear.

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