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

Annotations already indicate idempotentHint=true and readOnlyHint=false, which align with marking a todo complete. The description adds no extra behavioral details (e.g., side effects, permissions), but does not contradict annotations.

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

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

The description is a single 5-word sentence with zero waste, perfectly concise for a simple action.

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 state-change tool with one parameter and good annotations, the description is minimally adequate. However, it lacks context about permissions, return value, or what 'completed' entails, making it slightly incomplete.

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% documentation coverage for its single parameter 'todo_id' as 'Basecamp resource identifier'. The tool description does not enhance this meaning, but baseline is 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 'Mark a todo as completed' clearly states the action and resource, and distinguishes from the sibling tool 'basecamp_uncomplete_todo'. It is direct but could be more explicit about the state change.

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

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

No guidance is provided on when to use this tool versus alternatives like 'basecamp_update_todo' (which could also change completion status). There is no mention of prerequisites or contexts where this tool is appropriate or not.

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 operation (readOnlyHint=false) but not destructive or idempotent. The description adds that content must be HTML, which is a useful behavioral constraint. However, it does not explain side effects (e.g., whether it triggers notifications) or any rate limits, so transparency is adequate but not enriched 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?

Two sentences with no redundant words. The first sentence states the purpose, the second provides a critical formatting constraint. Every sentence is necessary and efficiently written.

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 (3 required params, no output schema), the description covers the core action and a key constraint. However, it omits details about the return value or confirmation, and does not mention how the answer relates to the check-in question or whether it is immediately visible. This is adequate but not complete.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description adds no new parameter details beyond stating that content must be HTML, which is already in the schema's content description. Thus, it meets the baseline but adds no extra value for parameters.

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

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

The description clearly states the tool creates a new answer for a check-in question, using a specific verb and resource, and distinguishes it from sibling tools like basecamp_create_comment or basecamp_create_message by mentioning 'check-in answer'. The requirement that content must be HTML is also specified.

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

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

No guidance on when to use this tool versus alternatives (e.g., basecamp_get_answer for retrieving, or other create tools). It does not mention prerequisites, such as needing to have or know the question_id, or whether the check-in must be active.

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-read-only, non-destructive, non-idempotent behavior. The description adds no additional behavioral context (e.g., side effects, permissions, rate limits) beyond what annotations provide. 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.

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

Single sentence, front-loaded key action and scope. No extraneous words. Efficiently communicates the tool's purpose.

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

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

For a simple creation tool with two parameters and no output schema, the description covers the essential purpose and acceptable resources. Could mention that the comment is created and possibly returned, but not required. Lacks guidance on error states or validation.

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?

Parameter descriptions in the schema are comprehensive (100% coverage). The description adds no additional meaning beyond restating 'Add a comment' and listing examples. Baseline score of 3 is appropriate given high schema coverage.

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

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

The description explicitly states the action ('Add a comment'), the resource ('to any Basecamp resource'), and lists example resource types ('message, todo, card, etc.'). This clearly distinguishes it from sibling tools like basecamp_create_message.

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?

While the description identifies the target resources, it does not explicitly guide when to use this tool versus alternatives (e.g., basecamp_update_comment) or state prerequisites (e.g., needing a valid recording_id). No when-not or context exclusions are provided.

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

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

The description goes well beyond the annotations to explain important behaviors: the expected HTML subset, how mentions/images/galleries work via bc-attachment tags, that Basecamp auto-enriches attachments after saving, and that existing enriched tags are automatically collapsed before content operations — telling the agent not to strip them manually. This is substantial behavioral disclosure that prevents likely mistakes.

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 one-line purpose followed by a bulleted HTML reference. It's lengthy but appropriately so given the complexity of Basecamp's HTML content requirements. Every bullet serves a functional purpose — no filler. The opening sentence is front-loaded.

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

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

Given the rich schema (100% parameter coverage) and detailed behavioral notes, the description is quite complete for a create operation. No output schema exists, so the return format isn't specified, but that's a platform limitation rather than a description gap. Minor: could mention that the created document can later be retrieved via get_document or listed via list_documents, but this is not essential.

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 covers 100% of parameters with descriptions. The description adds meaningful value by explaining the content parameter's HTML requirements in depth and clarifying the status enum values. Slight deduction because the description doesn't address vault_id discovery (e.g., how to find vault IDs via list_vaults), though the schema description is adequate.

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 'Create a new document in a vault' — a specific verb (create), resource (document), and location (vault). It is easily distinguished from siblings like basecamp_update_document, basecamp_create_message, or basecamp_create_vault.

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 and schema explain how to use the tool, including a detailed HTML formatting guide and status values ('active' to publish, 'drafted' for drafts). It doesn't explicitly name alternative tools for when NOT to use it, but the clear scope makes usage conditions fairly evident. Minor gap: no mention of when to prefer create_vault or update_document 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?

Annotations indicate readOnlyHint=false (write operation) and idempotentHint=false, but the description does not add behavioral context beyond that. It does not disclose potential side effects (e.g., notifications, card visibility), auth requirements, or what happens after creation. The extensive HTML rules relate solely to content formatting, not to tool 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 core purpose is in a single, front-loaded sentence, which is good. However, the description then dives into a lengthy, detailed HTML formatting guide that, while necessary for rich content, is verbose and may overwhelm the agent. The structure is organized with bullet points, but the length makes it less concise than ideal.

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

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

The tool has 7 parameters, no output schema, and sparse annotations. The description does not explain the return value, error conditions, or prerequisites (e.g., a valid column_id, authentication state). It provides HTML rules for content but omits other operational details. For a write operation of this complexity, the description is incomplete.

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 covers 71% of parameters with descriptions. The description adds meaningful guidance for the 'content' parameter through the detailed HTML rules, which is valuable and goes beyond schema. However, it does not clarify semantics for parameters like title (no schema description) or column_id beyond the schema's 'Basecamp resource identifier'. Given the partial coverage, the description partially compensates but not fully.

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 first sentence clearly states 'Create a new card in a kanban column with optional checklist steps.' This is a specific verb+resource and distinguishes it from siblings like create_todo or move_kanban_card. The tool name and title reinforce the purpose, 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.

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 basecamp_create_todo or basecamp_create_message. It does not state prerequisites, exclusions, or conditions that would help an agent decide between similar create tools. The only hint is 'kanban column' in the first sentence, but no explicit direction 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?

The annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, establishing the operation as a non-destructive write. The description adds no further behavioral detail—such as whether the message becomes immediately visible—so transparency relies solely on the annotations.

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

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

The description is a single sentence that directly states the tool's purpose without unnecessary detail. It is appropriately sized for the simplicity of the operation, with the schema carrying the bulk of the detailed guidance.

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

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

The description is minimal but sufficient given the comprehensive input schema and annotations. It does not mention required fields, but those are explicit in the schema, and there is no output schema to describe. Overall, the agent has enough context to 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?

All five parameters are documented in the input schema with descriptions, including the enum for status and the detailed HTML content rules. The tool description itself does not add any parameter information beyond the schema, so parameter semantics are fully covered by 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 states a specific action ('Create a new message') and a target resource ('in a Basecamp message board'), clearly distinguishing it from list/get/update sibling tools like basecamp_list_messages and basecamp_update_message.

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 does not explicitly mention when to use this tool compared to alternatives, but the verb 'Create' and the noun 'message' imply it is for new message creation. No explicit when-not or alternative references are present, so usage guidance is only implied through the tool's name and phrasing.

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 discloses important processing behaviors, such as Basecamp auto-enriching bc-attachment tags after saving and automatically collapsing already-enriched tags to minimal form before content append/prepend operations. This goes beyond the basic annotations (readOnlyHint=false, idempotentHint=false) and provides useful implementation 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?

The description begins with a concise purpose statement, followed by a well-structured list of HTML rules. While long, every bullet point is necessary for correctly formatting content, and the organization aids readability.

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

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

The description covers content formatting thoroughly but does not mention return values, error handling, or other side effects beyond creation. Given the absence of an output schema and the straightforward nature of a create operation, this is sufficient, though a brief note on the expected response would improve completeness.

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 descriptions cover 71% of parameters. The description adds significant meaning to the 'content' parameter by detailing allowed HTML elements and formatting rules. It also clarifies due_on and starts_on behavior through schema descriptions, leaving little ambiguity.

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 'Create a new todo item in a todo list.' It identifies the specific action (create) and resource (todo), distinguishing it from siblings like basecamp_update_todo and basecamp_list_todos.

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 extensive HTML formatting rules for the content parameter, which serves as usage guidance for how to format content. However, it does not explicitly mention when to use this tool versus alternatives (e.g., update_todo), leaving the selection criterion implied by the name and purpose.

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 aligns with annotations (write operation, not destructive). However, it does not add behavioral context beyond creation, such as whether it returns the created vault or has side effects. Annotations already cover basic traits.

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

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

The description is one sentence, concise and front-loaded. It could benefit from a brief usage note, but it is efficient overall.

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

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

For a simple create tool with two params and no output schema, the description is adequate but missing expected return value. It does not explain what a vault is or the nesting depth.

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 both parameters have descriptions. The description uses 'under a parent vault' to hint at parent_vault_id, but adds no new 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 it creates a new vault (folder) under a parent vault, using a specific verb and resource. It distinguishes from sibling tools like basecamp_update_vault and basecamp_list_vaults.

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

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

No guidance on when to use this tool versus alternatives, such as when to choose create_vault over update_vault or list_vaults. Prerequisites (e.g., parent vault must exist) are not mentioned.

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?

Adds behavioral details beyond annotations: explains return behavior for images (LLM sees directly) vs text files, and outlines extraction process. Annotations already indicate read-only/idempotent.

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

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

Two sentences, front-loaded with purpose, followed by essential extraction and behavior details. No extraneous 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?

Fully covers the simple tool's purpose, parameter extraction, and return types. No missing information for an LLM 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 covers all parameters with descriptions. Description adds extraction guidance and clarification on content_type fallback, 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?

Description clearly states verb 'download' and resource 'inline attachment from <bc-attachment> tag', distinguishing it from sibling tools like basecamp_get_upload which handles uploads by 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?

Provides specific source (href attribute) and extraction guidance for parameters. Implicitly tells when to use (when encountering <bc-attachment>), but lacks explicit mention of alternatives or 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds no further behavioral context (e.g., authentication, rate limits, return format).

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

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

Single sentence, front-loaded, zero waste. Maximally concise while being informative.

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

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

For a simple read-only single-parameter tool with comprehensive annotations, the description is sufficient. No output schema but return value is implicitly the answer object.

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 parameter description 'Answer ID'. Description adds no additional meaning beyond schema 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?

Description clearly states verb 'Get', resource 'check-in answer', and method 'by its ID'. Distinguishes from sibling basecamp_list_answers that lists multiple.

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?

Implied usage (when you have a specific answer ID) but no explicit when-not or alternatives. Sibling basecamp_list_answers exists for listing, but not mentioned.

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, destructiveHint, idempotentHint; description adds only 'full content' context, no additional 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?

Single sentence, front-loaded, concise with 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?

Adequate for a simple get tool with one parameter; mentions 'full content', but lacks return value details (no output schema). Could be improved slightly.

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 parameter description; description adds no new parameter-level meaning 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 clearly states verb 'Retrieve' and resource 'a single document' with scope 'full content', distinguishing it from list and create tools.

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

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

No explicit guidance on when to use this tool vs alternatives like basecamp_list_documents; usage is implied but not stated.

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, destructiveHint=false, and idempotentHint=true, so the description adds little behavioral context. It does not contradict annotations but also does not expand on effects like network dependencies or expected response structure.

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

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

The description is a single clear sentence, appropriately concise for a simple get operation. It avoids unnecessary detail while conveying the 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?

With no output schema, the description should hint at return fields. 'All details' is vague; an agent cannot infer what properties the card has (e.g., title, column, due date). The description is incomplete for such a 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 single parameter 'card_id' is fully described in the input schema (100% coverage). The description adds no additional meaning beyond what the schema provides, meeting the baseline for a well-covered 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 ('Get') and the resource ('kanban card'), and distinguishes this tool from siblings like 'basecamp_list_kanban_cards' which retrieves a list rather than a single card's full details.

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

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

The description implies usage when a specific card's details are needed, but does not explicitly state when to use this tool versus alternatives like listing or searching 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the exact fields returned (id, name, email, title, attachable_sgid), which is behavioral information 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?

Two sentences, front-loaded with purpose and list of fields, followed by a clear alternative. 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?

For a simple read operation with no parameters and rich annotations, the description provides all necessary context: what it retrieves and when to use an alternative. Output schema is not present, but the fields are described in text.

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

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

There are zero parameters, so the baseline for parameter semantics is 4. The description does not need to add further parameter info as the schema is already complete.

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 retrieves the full profile for the authenticated user, listing specific fields. It distinguishes itself from the sibling basecamp_whoami by being the tool for full profile data.

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 tells when not to use this tool: for a simple login check, use basecamp_whoami instead. This provides clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description adds minimal value. It simply restates the read operation without additional behavioral context like authentication needs or response specifics.

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

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

The description is a single, efficient sentence with no redundant information. Every word is necessary and front-loaded.

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

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

While the tool is simple, there is no description of the return value or potential errors. Given no output schema, the description could briefly mention what data is returned (e.g., message fields). It's adequate but not thorough.

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

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

Schema coverage is 100% and the parameter description already explains 'Message ID to retrieve'. The tool description adds no extra semantic meaning beyond what the schema provides.

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

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

The description clearly states the action (retrieve) and resource (single message from a Basecamp message board). This distinguishes it from sibling get tools like basecamp_get_answer or basecamp_get_document.

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

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

No guidance on when to use this tool versus alternatives such as basecamp_list_messages or other get tools. The context of retrieving a specific message vs listing all messages is not addressed.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no behavioral details beyond 'Get details', such as authentication requirements, rate limits, or what happens if the person does not exist. The annotations carry the burden, but the description offers minimal additional 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 a single sentence with no wasted words. It is appropriately concise for a simple retrieval tool, though it could slightly expand on the nature of the details returned.

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

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

Given the rich set of sibling tools (including many get_X variants) and the lack of an output schema, the description is too minimal. It does not explain what 'details' include, such as fields or relationships, nor does it provide hints about when to prefer this over list_people. The description feels incomplete for the context.

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

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

Schema description coverage is 100%, with the parameter 'person_id' described as 'Basecamp resource identifier'. The description repeats no parameter details and adds no additional meaning. Baseline score of 3 applies because the schema is sufficient.

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 'Get details about a specific person' clearly states the verb (get) and resource (person), and implicitly distinguishes from sibling tools like basecamp_list_people which list multiple persons. This is 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.

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 basecamp_list_people. The description does not indicate that it requires a person_id or that it is for retrieving a single entity, leaving the agent to infer usage from the schema alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by specifying what is retrieved: 'name, description, dock configuration, and metadata', going beyond the annotation safety profile.

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

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

Very concise: two sentences plus a short examples section. Action is front-loaded, no unnecessary words.

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

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

For a simple one-parameter read tool with rich annotations, the description adequately covers behavior, parameters, and return content (name, description, dock, metadata). No output schema required.

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

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

Input schema has 100% description coverage for the single parameter 'project_id'. The description does not add additional meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states 'Fetch detailed information about a specific Basecamp project' with specific verb and resource. It distinguishes itself from listing tools like basecamp_list_projects and other get tools by focusing on project details.

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 two explicit usage examples ('Get details for project 12345', 'Need full project information including dock configuration'). Does not explicitly state when not to use or compare to siblings, but context implies it's for single-project retrieval with an ID.

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, which align with the 'get' verb. The description adds that the tool returns 'schedule and metadata', providing 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.

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

The description is a single sentence of 8 words with no unnecessary words. Every word adds value, making it concise and front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description adequately covers what the tool does and what it returns ('schedule and metadata'). The mention of 'automatic' clarifies the type of question. No further detail is necessary.

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 covers the single parameter (question_id) with description 'Question ID' at 100% coverage. The description does not add any additional meaning beyond what the schema already provides, so 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 the verb 'Get', the resource 'single automatic check-in question', and specifies the return includes 'schedule and metadata'. This distinguishes it from sibling get tools like basecamp_get_answer or basecamp_get_document.

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

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

The description implies usage when wanting a single check-in question but does not provide explicit guidance on when to prefer this over other get tools, nor any exclusions or 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 already declare readOnly, idempotent, non-destructive. Description adds return behavior (number of questions and URL) but lacks details on error conditions, permissions, or response format 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.

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

Two sentences with no redundant information. Front-loaded with action and resource. Every word 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 low complexity (1 param, no output schema), description is mostly adequate but could clarify the return format (e.g., whether URL is for the questionnaire itself) and mention error cases. Annotations cover safety, so not a major gap.

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

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

Schema description coverage is 100% (parameter has basic description). Tool description does not add new semantic meaning for the parameter, e.g., how to obtain questionnaire_id or its relationship to a project. Baseline score of 3 applies.

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

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

The description clearly states the tool retrieves a questionnaire (check-ins container) for a project, with specific return info (number of questions and URL). The name 'questionnaire' distinguishes it from sibling 'get_question' and other get_* tools.

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

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

No guidance on when to use this tool vs alternatives, such as when to use get_questionnaire versus get_question or list_questions. No prerequisites or context provided (e.g., how to obtain questionnaire_id).

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 that it 'returns todo lists and groups', which provides some behavioral context beyond annotations, but lacks details on pagination, errors, or the structure of the returned data.

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

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

The description is very short (one sentence) and front-loaded with the key action and resource. It achieves conciseness, but it could be slightly more structured to include usage context or parameter clarification.

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

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

The tool is simple (1 param, read-only) with rich annotations, but the description does not fully compensate for the lack of an output schema. It hints at the return value ('todo lists and groups') but does not describe the exact format or grouping, leaving some ambiguity.

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

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

The input schema has 100% description coverage, but the schema description ('Basecamp resource identifier') is vague and does not explain how to obtain the todoset_id. The tool description does not supplement parameter meaning, forcing the agent to rely on external knowledge.

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 ('Get') and resource ('todo set container for a project'), and mentions what it returns ('todo lists and groups'). While it doesn't explicitly differentiate from siblings like basecamp_list_todos, the purpose is specific and understandable.

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

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

No guidance on when to use this tool versus alternatives (e.g., basecamp_list_todos). There is no mention of prerequisites, context, or when it should not be used, leaving the agent without decision support.

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 safe read-only behavior. The description adds valuable behavioral context: it describes what is returned for different file types (content vs metadata), which goes beyond annotations. It could mention potential size limits or error cases, but the provided details are substantial.

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 (two sentences) and front-loaded with the core action. Every sentence adds value without redundancy or fluff.

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

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

Given the simple single-parameter input and no output schema, the description fully covers the tool's behavior by explaining per-file-type return handling. It provides sufficient context for an agent to understand what to expect.

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

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

The only parameter, 'upload_id', has a clear schema description. The tool description does not add additional meaning beyond what the schema already provides. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('upload'), and differentiates behavior by file type (images, text, binary). This clearly distinguishes from sibling tools like 'basecamp_list_uploads' and 'basecamp_download_blob'.

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

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

The description implies usage (e.g., to retrieve content of images/text files), but does not explicitly state when to use this tool versus alternatives like 'basecamp_download_blob' for raw byte access or 'basecamp_list_uploads' for metadata listing.

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

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

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by specifying that the response includes counts of documents, uploads, and sub-vaults, which is not captured in annotations.

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

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

The description is a single, clear sentence that front-loads the main action and key details. Every word serves a purpose, with no redundancy.

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

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

Given the absence of an output schema, the description partially compensates by mentioning counts returned, but it does not fully detail all fields or response structure. For a get tool, more completeness on return values would be helpful, but annotations cover safety aspects.

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% coverage for the single parameter 'vault_id', with a description. The tool description does not add any extra meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves details of a vault, specifying it includes document, upload, and sub-vault counts. The verb 'Get' and resource 'vault' are specific, distinguishing it from sibling tools like get_document or get_upload.

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 does not provide explicit guidance on when to use this tool versus alternatives like list_vaults or other get tools. The purpose is clear, but no when-to-use or when-not-to-use context 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns answer content, author, and date, but does not reveal additional behavioral traits such as pagination or error conditions. It does not contradict annotations.

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

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

The description is a single sentence of 15 words, conveying the purpose and return values without any redundancy. It is optimally concise and front-loaded.

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

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

Given the tool's simplicity (one required parameter, no output schema, and straightforward behavior), the description covers the essential aspects. It does not mention pagination or error handling, but these are not critical for a simple list operation with only one parameter. Slightly above the minimum viable.

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% for the single parameter (question_id) with a generic description. The tool description adds no further meaning beyond stating 'specific check-in question'. Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('list') and resource ('answers to a specific check-in question'), and specifies the return fields (content, author, check-in date). This differentiates it from siblings like basecamp_get_answer (single answer) and basecamp_create_answer (create).

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 does not provide explicit guidance on when to use this tool versus alternatives. It implicitly requires a question_id, but does not contrast with basecamp_get_answer or other list tools. Minimal guidance is present.

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, destructiveHint=false, idempotentHint=true. The description adds behavioral details like OR-matching on multiple values and date flexibility, which go beyond the annotations. No 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.

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

The description is concise, well-structured with bullet points and examples, and front-loaded with the core purpose. 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?

Given the tool's simplicity (read-only, no output schema) and rich schema annotations, the description covers key aspects. It explains filters and usage but could mention return format (e.g., message objects). Still, it is nearly 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%. The description adds value by explaining OR-matching, providing concrete examples for each parameter, and clarifying default behavior (e.g., limit default 20). This exceeds the baseline 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 'Browse chat messages from Basecamp Campfires' and distinguishes it from message board tools like list_messages by specifying 'real-time chat rooms'. It lists specific use cases and provides examples.

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

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

The description explicitly states when to use the tool (browse recent activity, find by person, search, review history) and provides clear examples. However, it does not mention when not to use it or alternatives (e.g., list_messages for message board messages), which slightly reduces the score.

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 and idempotent behavior; the description adds that the tool works universally on all recording types, providing useful context beyond annotations. However, it does not detail pagination or ordering of results.

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

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

Two concise sentences that front-load the purpose with no wasted words. 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?

The tool is simple with one parameter and no output schema; the description adequately explains the scope and behavior, and the sibling tools provide sufficient context.

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

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

Schema coverage is 100% and the description reinforces the parameter meaning by explaining it works on any resource. The description does not add new information beyond the schema, so 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 the verb 'List' and the resource 'comments', and specifies it works universally on all recording types, distinguishing it from other list tools like list_messages or list_todos.

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 implicitly states when to use this tool (to list comments on any resource) and there are no direct alternatives for listing comments among siblings, but it does not explicitly state when not to use or mention 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, idempotent read operation. The description adds no further behavioral details, but also does not contradict annotations.

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

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

The description is a single clear sentence with no wasted words. It is appropriately concise for a simple list 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?

The tool is simple and annotations cover safety, but the description lacks information about return format, pagination, or behavior when no filter is provided. It is adequate but not complete.

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

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

Schema coverage is 100% with both parameters described. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'list' and the resource 'documents in a vault'. It distinguishes from siblings like basecamp_create_document and basecamp_get_document, which involve different actions.

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

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

No guidance on when to use this tool versus alternatives like basecamp_get_document or other list tools. No context on prerequisites or typical use cases.

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, destructiveHint, and idempotentHint. The description adds no additional behavioral context beyond the obvious listing action. It does not contradict 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 extremely concise with a single sentence that effectively front-loads the core purpose. Every word earns its place.

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

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

Given no output schema, the description does not explain what the response contains (e.g., full card details or IDs) or any pagination behavior. This leaves gaps for a list 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% with the single parameter 'column_id' described as 'Basecamp resource identifier.' The description adds no extra meaning beyond the schema, missing context like how to obtain the column ID.

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 cards in a kanban column,' which is a specific verb and resource. It distinguishes from sibling tools like basecamp_create_kanban_card and basecamp_move_kanban_card.

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

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

No usage guidelines are provided. The description doesn't indicate when to use this tool versus alternatives like basecamp_list_kanban_columns or basecamp_get_kanban_card, nor does it mention prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, indicating a safe read operation. The description adds no further behavioral traits (e.g., no side effects, pagination, or rate limits), so it contributes minimal extra transparency.

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

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

The description is a single concise sentence with no unnecessary words, perfectly front-loaded with the action and resource.

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 one parameter and rich annotations, the description is adequate but lacks details about the output format (e.g., column names, order). No output schema is provided, so the description could be more helpful.

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% as the single parameter 'card_table_id' has a description 'Basecamp resource identifier'. The tool description does not add any additional context or clarifications beyond the schema, so it meets the baseline.

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

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

The description 'List all columns in a kanban board' clearly states the action (list) and resource (columns in a kanban board), distinguishing it from siblings like basecamp_list_kanban_cards and basecamp_get_kanban_card.

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

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

No guidance on when to use this tool versus alternatives is provided. The description lacks context on prerequisites, such as the need for a card_table_id, and does not mention when to prefer listing columns over listing cards or 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description does not need to repeat these. It adds no further behavioral context beyond stating 'List messages,' which aligns with 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.

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

The description is two sentences long, each serving a distinct purpose: the first states the primary function, the second provides usage guidance. No extraneous words, and the main action is front-loaded.

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

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

For a straightforward listing tool with full schema coverage and comprehensive annotations, the description is complete. It covers purpose, scope, and alternative usage, and no output schema is needed.

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

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

Schema description coverage is 100%, so the schema adequately documents both parameters. The description does not add additional meaning or context beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool lists messages within a single Basecamp message board/project. It uses specific verb-resource pairing and distinguishes from the sibling tool basecamp_list_recordings by noting the scope difference.

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 tells when not to use this tool and provides an alternative: 'For cross-project or time-based browsing across content types, use basecamp_list_recordings instead.' This gives clear usage boundaries.

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 destructiveHint=false, so the agent knows it's a safe read operation. The description adds no new behavioral details (e.g., error handling, empty results, or output structure). It is adequate but does not go 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?

Single sentence with no redundancy. Each word serves a purpose. The description is efficiently front-loaded with the key action and scope.

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

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

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is minimally sufficient but lacks any mention of return format, typical use cases, or edge cases. It could be improved by noting that the result is an array of type objects or names.

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 a description for bucket_id ('Project/bucket ID'). The description does not add meaning beyond what the schema already provides, such as clarifying the concept of 'message types' or how they relate to the project.

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

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

Description explicitly states 'List available message types/categories for a Basecamp project', providing a clear verb (list), resource (message types/categories), and scope. This differentiates it from sibling tools like basecamp_list_messages, which lists actual messages.

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

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

No guidance on when to use this tool versus alternatives. For example, it does not mention that this tool may be needed before creating a message to obtain a valid type ID. The description lacks context on prerequisites or use cases.

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, destructiveHint, idempotentHint, and openWorldHint, so the description adds no additional behavioral context beyond confirming the listing operation.

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

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

The description is a single sentence that conveys the purpose efficiently with 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?

While the tool is simple, the description does not mention return format, pagination, or other potential behavioral details. With no output schema, some context is missing.

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

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

Schema coverage is 100% with a clear description of the filter parameter. The tool description does not add any meaning beyond what the schema already provides.

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

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

The description clearly states the action (list) and the resource (people) with scope ('all people in the Basecamp account'), distinguishing it from the sibling tool basecamp_get_person which retrieves a single person.

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

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

The description implies usage for listing people but does not explicitly state when to use this tool versus alternatives like basecamp_get_person, 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.

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns 'active projects' and 'visible to the authenticated user,' providing extra behavioral 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.

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

Two sentences, front-loaded with action and purpose, no wasted words. Efficient structure.

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?

Simple list tool with no output schema; description adequately covers return values and usage context. Could mention if pagination exists, but not critical.

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?

Single parameter 'filter' has identical description in schema and tool description ('Optional regular expression to filter projects by name or description'). Schema coverage is 100%, so baseline 3 applies with no additional value from description.

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

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

Description clearly states 'List all projects visible to the authenticated user' and specifies returned data (IDs, names, descriptions, metadata). Distinguishes from sibling tools like basecamp_get_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?

Explicitly tells when to use: 'Use this to discover project/bucket IDs needed for accessing messages, todos, and other resources.' Does not mention alternatives for non-list scenarios, but context is clear.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds specific return fields but does not disclose additional behavioral traits beyond the annotations.

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

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

The description is a single sentence that is concise, front-loaded, and provides essential information without unnecessary words.

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

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

For a simple list tool with one parameter and full annotations, the description adequately explains the return values. It lacks info on pagination, but this is not critical for basic usage.

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

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

Schema coverage is 100% and the parameter 'questionnaire_id' is described. The description adds that questions are within a questionnaire, but this does not significantly enhance the schema's 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 the tool lists all automatic check-in questions in a questionnaire, specifying the returned fields (title, schedule, paused status, answer count). This distinguishes it from sibling tools like basecamp_get_question (single question) and basecamp_list_answers (list answers).

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

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

The description implies use when needing to list questions for a given questionnaire, but does not explicitly mention when not to use it or provide alternatives. However, the context is clear and the tool is simple.

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 destructiveHint=false. The description adds that filters support multiple values for OR-matching, default behavior when omitting parameters, and lists specific recording types. 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 introduction, bullet points for use cases, an explicit comparison to sibling tools, and specific examples. Every sentence contributes 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?

With 9 parameters, all fully described in both schema and description, and no output schema (recordings list is self-explanatory), the description is complete with examples covering various scenarios.

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%, but the description adds significant context: clarifies that project_ids can be omitted to browse all projects, type defaults to common types, since accepts ISO/relative/keywords, query is case-insensitive, limit default and max, and provides multiple examples.

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 browses recent activity across Basecamp by listing recordings, explaining that recordings represent all content types. It distinguishes itself from per-resource list tools by noting cross-project, time-based, or multi-type activity browsing.

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 includes a 'When to use this vs. the per-resource list tools' section, naming specific alternatives like basecamp_list_messages, basecamp_list_todos, etc., and states when to use each.

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, destructiveHint=false, idempotentHint=true. The description adds filtering by status, which is useful but not behavioral beyond that. No mention of pagination, rate limits, or other traits.

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

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

One sentence, clear and front-loaded. However, it is too brief and omits necessary details like the completed parameter.

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 and low parameter coverage (33%), the description is incomplete. It does not explain the completed boolean parameter or any return behavior. More context is needed for effective 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?

Input schema has 3 parameters with 33% description coverage (only todolist_id has a description). The description mentions 'filter by status' but does not explain the status enum or the completed parameter. Schema coverage is low, and description fails to compensate.

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 todos in a todo list. Filter by status: 'active' or 'archived'.' This specifies the action (list) and resource (todos in a todo list), and distinguishes it from siblings like basecamp_complete_todo or basecamp_create_todo. It is clear but could be more precise about scope.

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

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

No guidance on when to use this tool vs alternatives. It does not mention when not to use or provide context for selecting this over other list tools like basecamp_list_answers.

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 readOnly, non-destructive, idempotent, and open-world hints. The description adds contextual location (vault) 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.

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

A single sentence with no unnecessary words. Front-loaded with the action and resource, highly 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?

Given the tool's simplicity and rich annotations, the description adequately covers the main purpose. However, it does not mention return format or pagination, which would be helpful but not critical.

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 parameters are already described in schema. The description does not add any new meaning beyond the schema's 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 clearly states the verb 'list' and resource 'files uploaded to a vault', and specifies the context 'Docs & Files section', distinguishing it from sibling tools like get_upload or list_vaults.

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

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

The description implies usage for listing uploads in a vault but provides no explicit guidance on when to use this tool over 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds modest context by specifying the operation's scope (sub-vaults under a parent vault in Docs & Files), but lacks details on pagination, limits, or empty responses. It does not contradict annotations.

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

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

The description is a single concise sentence that front-loads the purpose. It could be slightly expanded to mention the return format, but it effectively conveys the core information without waste.

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 simplicity of the tool (2 parameters, no output schema, read-only annotations), the description is minimally adequate. However, it omits details about return format (list of vault objects) and potential limitations, which would improve completeness.

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 adds extra meaning by noting that the parent_vault_id should be 'from the project's dock', which aids correct usage. The filter parameter's description in schema is already adequate.

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 the resource 'sub-vaults (folders)', and specifies the location 'under a parent vault in the Docs & Files section.' This effectively distinguishes it from sibling tools like basecamp_list_documents or basecamp_list_answers.

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 implicitly indicates when to use the tool—to list sub-vaults—but does not provide explicit guidance on when not to use it or alternatives. Sibling tools exist for listing other resources, but no exclusions or comparisons are 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?

Description adds that it 'opens a browser window' – behavioral detail not in annotations. Annotations indicate idempotent and non-destructive, which aligns. 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?

Three concise sentences, each carrying essential information. Front-loaded with main purpose. No unnecessary 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?

Complete for an auth tool: covers login purpose, OAuth browser interaction, and multi-account handling. Return value not described but output schema absent; still sufficient for agent usage.

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 already fully describes the parameter (100% coverage). Description reinforces the behavior of omitting vs providing account_id, adding context 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 'Authenticate with Basecamp via OAuth' – specific verb+resource. Distinct from all sibling tools which operate on Basecamp data after login.

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

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

Explicitly provides step-by-step guidance for multiple accounts: call without account_id to list, then call again with desired account_id. This is precise usage instruction.

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 context beyond the annotations by specifying what gets destroyed ('stored credentials'). Annotations already indicate destructiveHint=true and idempotentHint=true, but the description clarifies the exact effect. It lacks mention of any side effects (e.g., session invalidation), but given the simplicity, this 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.

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

The description is a single, short sentence that conveys the purpose without any unnecessary words. It is perfectly concise for the simplicity of the 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 the tool has no parameters, no output schema, and a straightforward purpose, the description is complete. It covers what the tool does with no missing information.

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

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

The tool has zero parameters and the input schema is fully covered (100%). The description does not need to explain parameters, so a baseline of 4 is justified.

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 'Remove stored Basecamp credentials.' uses a specific verb ('Remove') and resource ('stored Basecamp credentials'), clearly distinguishing it from the sibling tool 'basecamp_login' and other tools. It leaves no ambiguity about its function.

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

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

The description implies usage when the agent needs to clear stored credentials, but it does not explicitly state when to use this tool versus alternatives (e.g., when to logout vs. just not using credentials). No exclusions or prerequisites are mentioned.

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 false, destructiveHint false, and idempotentHint false. The description adds no additional behavioral context beyond the basic move action.

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

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

Single short sentence that efficiently conveys the core 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?

The description covers the basic purpose but omits information about return values, side effects, or prerequisites. Given the tool's simplicity and absence of output schema, it is minimally adequate.

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 does not elaborate on the parameters beyond what the input schema already provides. The schema covers 67% of parameters with descriptions, but the description field itself adds no parameter-specific 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?

Description clearly states 'Move a kanban card to a different column and/or position', which is a specific verb and resource. It distinguishes from sibling tools like create, get, list, and update by focusing on positional changes.

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

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

No guidance on when to use this tool versus alternatives like update_kanban_card. The description implies the use case but does not explicitly state exclusions or contexts.

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 does not contradict annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It adds the behavioral detail of undoing completion, but annotations already cover idempotency and non-destructiveness, so the description provides only marginal additional insight.

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

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

The description is a single, front-loaded sentence of 8 words with zero redundancy. Every word earns its place.

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

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

For a simple tool with one parameter, no output schema, and rich annotations, the description is adequate but lacks mention of preconditions (e.g., todo must be currently completed) or error scenarios. It could be slightly more 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?

The single parameter 'todo_id' is fully described in the schema with base description. The tool description adds no further semantics, such as where to obtain the id or any constraints, which is acceptable given 100% schema coverage.

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

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

The description clearly states the action: 'Mark a todo as incomplete (undo completion).' It uses a specific verb and resource, and it naturally distinguishes itself from the sibling 'basecamp_complete_todo' by being the inverse operation.

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

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

The description implies usage via 'undo completion,' but it does not explicitly state when to use this tool over alternatives like 'basecamp_complete_todo' or provide any context on 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.

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

Beyond the annotations' read/destructive flags, the description reveals valuable behavior: Basecamp auto-enriches bc-attachment tags after saving, and before partial operations it collapses existing enriched tags back to their minimal form. This prevents the agent from doing unnecessary cleanup and avoids mismatched find strings. It does not discuss idempotency, but the notable behaviors are covered.

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 first sentence fronts the primary purpose and the token-saving advice. The long HTML section is large, but every part supports the agent in generating correct content for a tool that accepts HTML. It is not overly wordy for the subject matter, although some rules could have been moved to a linked style guide.

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

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

The description is strong enough for an agent to operate effectively: it explains how to handle content, how partial operations behave, and how bc-attachment tags are processed. It does not mention return values, but there is no output schema to satisfy. A mention that the updated comment is returned would push it to a 5, but the current coverage is good.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance by recommending partial operations to save tokens and explaining how append/prepend/search_replace interact with bc-attachment tags (auto-collapsed first). It also supplies essential HTML formatting rules for constructing valid content values, providing more semantic help than the schema alone.

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

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

The description opens with 'Update a comment', a specific verb and resource, which clearly sets it apart from sibling create_comment and list_comments. It does not explicitly contrast itself with these siblings or state that it operates on existing comments, so it stops short of a 5.

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

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

The instruction to use partial content operations when possible is good parameter-level guidance, but it does not explicitly say when to choose this tool over alternatives such as create_comment or update_message. The intended use is implied by the name and title rather than stated explicitly.

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 and openWorldHint=true, so the tool is a mutation. The description adds valuable behavioral details: bc-attachment tags are auto-enriched after saving and collapsed before content operations, with a warning not to strip them manually. This goes beyond what annotations provide and helps avoid misuse.

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 long due to necessary HTML rules, but it is well-structured with bullet points and front-loads the purpose. Every sentence contributes to correct usage, though it could be trimmed slightly without loss of clarity.

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 HTML content, mentions, attachments, and multiple update modes, the description is comprehensive. It covers allowed tags, paragraph spacing, headings, lists, tables, mentions, images, highlights, and the behavior of enrichment. There is no output schema, so no return-value documentation is needed. The tool is fully specified for correct invocation.

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

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

Schema coverage is 100% with all parameters described. The description adds HTML formatting rules relevant to the content parameter, and clarifies the mutual exclusivity of content vs. partial operations (already in schema). This adds some value but doesn't significantly go beyond the schema's own descriptions.

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

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

The description opens with a clear 'Update a document.' which is a specific verb and resource. It distinguishes from siblings like basecamp_create_document and basecamp_get_document by its mutation focus on an existing document.

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

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

The description explicitly advises 'Use partial content operations when possible to save on token usage', giving clear guidance on parameter selection. It doesn't explicitly name alternatives like create_document, but the purpose is obvious from the context. The guidance is actionable.

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 discloses many behaviors, such as steps deletion, partial operations, and HTML auto-enrichment. However, it contradicts the destructiveHint=false annotation by stating 'Steps not in array will be deleted', which indicates destructive behavior. This is a clear contradiction, so the description fails to align 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 long but well-structured, starting with the core operation and key constraints, then providing necessary HTML formatting rules. It is front-loaded with the token-saving tip and required-field note. The length is justified by the complexity of the content format, so it is appropriately sized.

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

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

The description covers essential aspects: required fields, mutual exclusions, steps deletion, and HTML rules. However, it does not explicitly state that this tool is for updating existing cards only, and the destructiveHint contradiction creates confusion about destructive behavior. It also lacks error or permission notes, but given the complexity, it is fairly complete but not flawless.

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 adds significant meaning beyond the schema by detailing allowed HTML tags and formatting rules for content, which the schema does not provide. It also reinforces mutual exclusions and partial operations. With schema coverage at 100%, the baseline is 3, but the HTML rules and auto-enrichment details add substantial value, raising the score.

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 a kanban card including its steps', specifying the action and resource. It distinguishes from siblings like create_kanban_card and update_todo by being specific to kanban cards. It also notes the required-field constraint, adding clarity.

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 advises using partial content operations to save tokens, which is a helpful usage guideline within the tool. However, it does not explicitly differentiate from alternatives like create_kanban_card or update_todo; the differentiation is implied by the name and purpose rather than stated.

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

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

The description goes far beyond the annotations, explaining that Basecamp auto-enriches bc-attachment tags after saving, that existing enriched tags are collapsed back to minimal form before partial operations, and exactly which tags/styling are allowed. Even though annotations already carry the mutation profile (readOnlyHint=false, destructiveHint=false), this content-rich behavioral context is genuinely additive.

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

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

The description is long, but the multiple HTML and attachment rules are information-dense and necessary for correct invocation. It is front-loaded with the token-saving tip and uses clear bullets for the rule sharkline; little is wasted.

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

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

For a mutation tool with 7 parameters, no entire-notes structure, and no output schema, the description does the heavy lifting: HTML syntax, highlight values, attachment handling, and idempotency. Gaps such as the response format and permission requirements exist, but the core calling contract is well covered.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real parameter semantics beyond the schema by explaining how content, content_append, content_prepend, and search_replace interrelate and how attachment content behaves in each case. It doesn't document every parameter in prose, but the schema already does that.

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?

"Update a message" states a specific verb and resource, and the sentence about partial content operations clarifies the scope of the tool. It doesn't explicitly differentiate the tool from siblings like basecamp_update_comment or basecamp_update_document, but the verb-resource pairing and title make the target unambiguous.

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

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

The description gives concrete usage guidance: prefer partial operations (append/prepend/search_replace) over full content replacement when possible to save tokens. It does not spell out when to choose this tool over an alternative like basecamp_create_message, but the guidance within the tool's own operation modes is clear and actionable.

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

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

The description adds meaningful behavioral details beyond the annotations, such as how bc-attachment tags are auto-enriched and how content operations automatically collapse enriched tags. It does not contradict the annotations, which mark the tool as non-readonly, non-destructive, and idempotent.

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 long but appropriately so, given the complex HTML formatting rules for Basecamp content. It is front-loaded with the purpose, followed by practical usage guidance. The structure is logical, though the sheer volume of formatting rules makes it less concise than ideal.

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

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

The description covers the tool's purpose, content editing strategies, and detailed HTML requirements, which is sufficient for the tool's complexity. It does not mention return values, but there is no output schema and the focus is on the action, so this is not a significant gap.

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

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

The input schema already provides 100% parameter coverage with clear descriptions. The description adds extra semantic value by explaining HTML content rules and advising when to use content_append/content_prepend/search_replace instead of content, which enhances understanding of the content-related parameters.

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

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

The description clearly states 'Update a todo item', giving a specific verb and resource. It distinguishes this from sibling tools like update_comment, update_message, and update_document without ambiguity.

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 useful guidance on using partial content operations to save tokens and includes extensive HTML formatting rules. However, it does not explicitly explain when to choose this tool over alternatives such as complete_todo or uncomplete_todo, so usage context is only partially implied.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds minimal behavioral context beyond confirming it updates only the title, which is consistent but not additive.

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

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

The description is a single, front-loaded sentence with no redundancy. Every word contributes to clarity.

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 update tool with two parameters and good annotations, the description is adequate. It could explicitly state that only the title can be updated, but the completeness is satisfactory.

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 clear descriptions for both parameters. The description does not add extra meaning beyond what the schema provides.

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

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

The description clearly states the action (update), the resource (vault), and the specific field (title), distinguishing it from create, get, and list vault 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?

While the description is clear on what the tool does, it does not explicitly state when not to use it or mention alternatives. However, the context from sibling tool names provides implicit guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it returns authentication status and basic identifiers, which is consistent and transparent.

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

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

Two concise sentences, front-loaded with action, no wasted words. Perfectly structured.

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

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

Tool is simple with no parameters or output schema. Description fully explains what it does and points to alternative for richer profile. Complete for its complexity.

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

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

No parameters; schema coverage 100%. Baseline 4 is appropriate since description adds no parameter info but explains output.

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?

Clear verb 'check login state' and specific outputs: authentication status, user + account id. Distinct from sibling basecamp_get_me for full profile.

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

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

Explicitly states when to use (check login state) and when to use alternative basecamp_get_me for full profile. Provides clear context.

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