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 already declare this is a non-read-only, non-idempotent, non-destructive, open-world write. The description adds one genuinely useful behavioral constraint — content must be HTML — but says nothing about whether an answer is appended to an existing one, whether the author is the caller, or what happens on error. With annotations carrying the safety profile, a 3 fits.

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

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

Two short sentences, purpose first, constraint second, no filler. Nothing to trim and the key requirement 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 write tool with no output schema, the description is thin: it never says what a successful call returns (e.g., the new answer ID) or how errors surface, and it omits the relationship between group_on and the check-in day grouping beyond the schema's own note. Annotations plus the rich schema keep it callable, but the description itself is only 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?

Schema description coverage is 100%, with the content parameter carrying an extremely detailed HTML spec and group_on explaining the YYYY-MM-DD grouping semantics. The description repeats only the HTML requirement and adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a new answer") and scopes it to a check-in question, which separates it from create_comment, create_message, and the read-side list_answers/get_answer siblings. It is clear but does not explicitly name any alternative tool or contrast with them.

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?

There is no guidance on when to use this tool versus basecamp_update_answer-like siblings (update path isn't present, but update_comment exists) or versus create_comment, and no prerequisites such as needing a valid question_id from list_questions. Usage is only implied by "for a check-in question."

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=false, openWorld=true, idempotent=false, and destructive=false, but the description adds critical behavior beyond them. It explains that the returned sgid is account-bound and does not expire, yet is shown only once and must be embedded in the same session. That ephemeral-output caveat is exactly the kind of operational detail an agent cannot infer from annotations or schema.

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

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

The description is front-loaded with what the tool does and why, then moves to usage, parameter choice, and the critical sgid caveat. Every sentence earns its place. There is no redundant restatement of the name or title.

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 four fully documented parameters, no output schema, and non-contradictory annotations, the description covers what an agent needs: when to call it, how to supply the file, and how to use the returned sgid. The only missing piece, return-value structure, is addressed functionally by explaining the sgid and embedding tag.

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 all four parameters are already documented in the input schema. The description only reinforces the file_path/url mutual exclusion and mentions the returned sgid's tag format. It adds little parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: upload a file to Basecamp and get an attachable_sgid. It clearly distinguishes this from read/list attachment siblings by explaining the create-and-embed workflow. The output sgid is named, making the tool's purpose 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?

Gives clear when-to-use guidance: showing an image or video in a message, comment, document, card, or todo when the file is not already in Basecamp. It includes concrete examples (external URL, screenshot on disk) and an implicit when-not condition. It does not name alternative sibling tools, so it stops short of explicit alternative routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the write/non-destructive profile is covered structurally. The description adds nothing beyond that — no note that this triggers notifications for mentioned people, no note that recording_id must resolve or the call fails, no mention of auth requirements.

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

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

A single short sentence with the action and scope front-loaded; nothing wasted and nothing buried.

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 two-parameter mutation whose annotations cover the safety profile and whose schema exhaustively documents content, the description is largely sufficient. It is slightly thin on where recording_id comes from and on the error behavior for invalid person IDs, but those are secondary.

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

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

Schema description coverage is 100% and the content parameter carries an extremely detailed HTML/mention/attachment spec, so the schema does the heavy lifting. The description adds no parameter-level detail of its own, which is the baseline-3 case.

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

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

States a specific verb ('Add') and resource ('comment') and broadens scope with examples of target resources (message, todo, card). It does not explicitly distinguish itself from the sibling basecamp_update_comment, but an agent can still tell what it creates.

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?

There is no when-to-use guidance, no when-not guidance, and no mention of the obvious alternative basecamp_update_comment. The agent must infer that this is for new comments versus edits.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses real behavior: invalid person IDs return an error and write nothing, bc-attachment tags are auto-enriched after saving, and enriched tags are auto-collapsed before append/prepend/replace operations. It does not state what a successful call returns or what permissions are needed, keeping it out of the top tier.

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?

Purpose is front-loaded in a single sentence followed by well-organized, scannable bullets. The content rules are long but are largely load-bearing domain knowledge; only a few clauses (e.g. the reassurance about not manually stripping tags) could be trimmed.

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 non-idempotent create tool with no output schema, the description covers the demanding part (content HTML format), error behavior, and attachment plumbing. Minor gaps remain: it never states where vault_id comes from (basecamp_list_vaults exists) or what the call returns on success.

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

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

Schema coverage is 100%, so the baseline is 3, but the description substantially enriches the 'content' parameter with an exhaustive HTML contract (allowed tags, paragraph spacing, list/table syntax, bc-attachment semantics) that goes well beyond the schema's one-line 'HTML document content'. The title, status, and vault_id parameters gain no extra meaning from the description.

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

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

The opening sentence states a specific verb and resource ('Create a new document in a vault'), which cleanly separates it from siblings like basecamp_create_message or basecamp_create_todolist. It stops short of naming the nearest alternatives (e.g. basecamp_update_document) or clarifying it creates in an existing vault, so it is clear but not maximally differentiated.

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?

There is no explicit when-to-use-this-vs-another-create-tool guidance, so the agent must infer selection from the resource name. It does provide strong procedural routing for sub-tasks, naming basecamp_list_people, basecamp_list_recordings, and basecamp_create_attachment for attachable_sgid sourcing, which is useful but not tool-selection 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 non-read-only, non-destructive, non-idempotent, open-world behavior, so the bar is lower. The description adds real behavioral context beyond that: mention tags trigger a notification, an invalid person ID 'returns an error and writes nothing' (all-or-nothing), and bc-attachment tags are auto-enriched after saving. It does not describe error behavior for bad column_id or the response shape.

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 purpose statement is front-loaded in the first sentence, followed by a well-organized bulleted HTML reference. The length is high, but nearly every rule is actionable guidance for the untyped 'content' field, so the bulk largely earns its place rather than being filler.

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

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

With no output schema and 7 parameters, the definition should ideally state the return value (e.g., the new card ID) and where column_id originates (basecamp_list_kanban_columns). Content formatting is covered exhaustively and annotations carry the safety profile, but the mutation lifecycle and required-ID sourcing are left 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?

Schema coverage is 71%, so most parameters are documented in-schema, but the free-form 'content' parameter has no schema description at all. The description fully compensates by specifying allowed HTML tags, paragraph wrapping requirements, mention/attachment syntax, and highlight variables. Minor parameters (title, due_on, notify, steps) are not elaborated beyond the schema, hence not a 5.

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 opening sentence 'Create a new card in a kanban column with optional checklist steps' gives a specific verb (create), resource (kanban card), and scope (column, optional steps). It does not explicitly distinguish itself from basecamp_update_kanban_card or basecamp_move_kanban_card, but the create framing is 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?

There is no explicit statement of when to use this tool versus basecamp_update_kanban_card or basecamp_create_todo. The description does route the agent to supporting tools for obtaining inputs ('Get person IDs from basecamp_list_people', 'upload it with basecamp_create_attachment'), which is useful workflow guidance, but it never addresses when this tool is the right choice.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds no behavioral context beyond that, such as what gets created, whether drafts are supported, or what happens on error.

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

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

The description is a single, front-loaded sentence with no filler or repetition. It is appropriately concise, especially given the rich input schema that carries the detailed documentation.

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 schema thoroughly covers inputs and annotations cover safety, but there is no output schema and the description does not explain what the tool returns. For a create operation, that is a meaningful gap, though the structured fields make the definition minimally 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 description coverage is 100%, so the schema itself fully documents all five parameters, including required fields, status enum, and the extensive HTML content rules. The description adds no parameter meaning, so the baseline of 3 applies.

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

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

The description gives a clear verb and resource (create a message) and scopes it to a Basecamp message board. It does not explicitly name or differentiate from sibling tools like basecamp_update_message or basecamp_get_message, so it falls short of the top tier.

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

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

No guidance is given on when to use this tool versus alternatives such as basecamp_update_message or basecamp_create_comment. The description only states the action, leaving all usage context to inference.

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

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

Annotations already declare this as a non-read-only, non-idempotent write, but the description adds real behavioral detail beyond them: mentions trigger notifications to the mentioned person, an invalid person ID causes an error and writes nothing (atomic failure), and bc-attachment tags are auto-enriched after saving. It does not, however, describe the response payload or permission requirements.

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

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

The one-line purpose is properly front-loaded, and the allowed-tag list is genuinely useful reference material for a tool with no output schema or docs field. However, the block is large and uneven: the paragraph-spacing explanation and the bc-attachment collapse rules (which describe behavior of append/prepend/search_replace operations, not this tool) consume significant budget and repeat points already implied.

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 the hardest part of the call — composing valid Basecamp HTML content — the description is thorough. But for a 7-parameter creation tool with no output schema, it omits where todolist_id should be sourced (basecamp_get_todoset / basecamp_list_todos) and never says what the call returns, so an agent cannot close the loop after creating the todo.

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

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

With 71% schema coverage, the schema already documents due_on, notify, starts_on, todolist_id, and assignee_ids; the description's heavy HTML contract adds substantial meaning for the undocumented 'content' parameter, including mention and attachment syntax and validation behavior. The 'title' parameter remains undocumented in both places, which keeps this short of a 5.

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 opening sentence gives a specific verb and resource ('Create a new todo item in a todo list'), which is enough to distinguish it from basecamp_create_todolist or basecamp_create_message by resource type. It never explicitly contrasts itself with those siblings, though, so the differentiation is inferable rather than stated.

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?

There is no guidance on when to use this tool versus siblings like basecamp_create_todolist, basecamp_create_comment, or basecamp_create_kanban_card, and no stated prerequisite (e.g., where todolist_id must come from). The description does route to basecamp_list_people and basecamp_create_attachment for obtaining IDs and SGIDs, which is procedural help, but it is about building the content payload rather than tool selection.

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

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

Beyond the annotations, the description discloses real behavioral traits: a bad person-id causes an error and writes nothing, mentions trigger notifications, bc-attachment tags are auto-enriched after saving, and existing enriched tags are collapsed before content edits. It does not cover permission requirements or the practical consequence of non-idempotent creation (duplicate lists).

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 front-loaded and the HTML rules are organized as a scannable bullet list. The block is long and dominates the definition, but nearly every bullet is necessary to produce valid content, so it is dense rather than wasteful.

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 three-parameter creation tool with no output schema, the description covers purpose, ID sourcing, content formatting, and key side effects/error behavior. It leaves the return value and required permissions unspecified, which are minor gaps given how much else is documented.

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 already 100%, so the baseline is 3, but the description adds substantial meaning: it explains where todoset_id comes from and elaborates the 'description' parameter with a full HTML contract (allowed tags, paragraph spacing, lists, tables, mentions, attachments, highlights). This is well beyond what the schema conveys.

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 opening sentence gives a precise verb and resource ('Create a new todo list in a todo set'), which cleanly separates it from siblings like basecamp_update_todolist, basecamp_create_todo, and basecamp_create_todolist_group. It stops short of naming any sibling explicitly, so it is clear but not maximally differentiating.

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

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

It provides one concrete prerequisite/routing hint: fetch todoset_id from the project dock via basecamp_get_project. However, it never states when to use this versus creating a todo, a todolist group, or an update, and gives no exclusions or prerequisites beyond the ID source.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine behavioral context beyond them: the default placement is the bottom, and placement behavior is conditional on the placement argument. It does not mention auth requirements or return format, but adds real value.

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

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

Three sentences, front-loaded with the core creation action, then workflow routing. Every sentence earns its place with no filler or restatement of the name.

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 4-param mutation tool with no output schema and annotations already covering safety, the description covers creation, default placement, and the follow-on workflow. The one minor gap is that it never states that the new group's ID is returned, which the agent needs to chain the suggested follow-up calls.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretation beyond the schema: it clarifies that the group ID returned is later passed as todolist_id to other tools, and explains the default bottom placement and the before/after dependency on relative_to_id. This is meaningful semantic framing not present in the schema.

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

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

States a specific verb and resource ('Create a group (section) in a todo list') and immediately clarifies the intent ('to split its todos'). This distinguishes it clearly from sibling tools like basecamp_create_todolist and basecamp_create_todo.

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 routes the agent: add todos via basecamp_create_todo (passing the group ID as todolist_id), move todos via basecamp_move_todo (destination_id), and rename/describe via basecamp_update_todolist. Both when-to-use and which-alternative are named, leaving nothing to inference.

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

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

The description 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the ordering contract (ungrouped todos first, then each group's todos) and that the response includes group sections including empty ones.

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 tight sentences with the core purpose front-loaded and no filler. The ordering detail is a bit dense but each sentence carries distinct information.

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

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

With no output schema, the description usefully explains the return shape (display order plus group sections including empty groups), which is exactly what an agent needs. The one gap is the undocumented 'completed' parameter, leaving the definition slightly short of complete for a 3-parameter 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 only 33%: only todolist_id is documented ('Basecamp resource identifier'). The description restates the status enum values (already in the schema) but says nothing about the third parameter, 'completed' (a boolean const true), which remains unexplained in both places.

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

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

States a specific verb and resource ('List todos in a todo list'), which is clearly distinct from siblings like basecamp_get_todoset, basecamp_create_todo, or basecamp_list_recordings. It does not, however, explicitly name an alternative to route against, so it falls 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 description explains how to filter ('active' or 'archived') but never says when to choose this tool over siblings such as basecamp_get_todoset, basecamp_list_recordings, or the group/move tools. No prerequisites or exclusions are given, so an agent gets no routing guidance.

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

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

Annotations already declare 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?

Annotations already declare non-destructive, idempotent, open-world behavior, lower the bar. The description adds genuinely useful semantics: 'If the other todo is in a different list or group, the todo moves there,' and 'Only the todos that are not complete have a position,' which the annotations do not convey.

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

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

Front-loaded one-line summary followed by tightly scoped examples; each sentence earns its place. Slightly verbose example block, but no filler.

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

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

No output schema exists, but the description, annotations, and 100%-covered schema together give an agent everything needed to select and invoke the tool correctly, including cross-list behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the interaction between destination_id and relative_to_id (fallback to the parent of relative_to_id, or staying in place), adding real 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?

States a specific verb and resource (move a todo) and enumerates the three distinct destinations: within its list, into a group/section, or into another list. It clearly separates itself from the sibling basecamp_reorder_todos by naming it.

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 three worked examples effectively show when each placement mode applies, and it explicitly routes bulk ordering to basecamp_reorder_todos. It lacks an explicit statement of when NOT to use this tool (e.g., cross-project limits), but the context is clear.

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

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

Annotations already declare the key traits: idempotentHint=true, destructiveHint=false, openWorldHint=true, readOnlyHint=false, so the mutation/idempotency profile is covered structurally. The description adds the project-scoped placement framing but says nothing about permissions, side effects on ordering of other lists, or the response. With annotations carrying the load, a 3 is appropriate.

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 short sentences with zero filler; the core action and scope come first, then the ID source, then the sibling routing. Every sentence earns its place.

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

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

For a simple 3-param mutation with no output schema and annotations covering safety, the description covers action, scope, ID sourcing and the closest alternative. Only minor gaps remain (ordering effects on sibling lists, error cases), so it is nearly 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 description coverage is 100%, including the placement enum and the relative_to_id conditional ('use only with before/after'), so the schema does the heavy lifting. The description adds nothing about parameter formats beyond that. 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?

States a specific verb ('Move') and resource ('a todo list') with scope ('to a different place among the todo lists of its project'), and explicitly distinguishes itself from the group-moving sibling basecamp_move_todolist_group. An agent can tell it apart from basecamp_move_todo and basecamp_reorder_todos without opening any schema.

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

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

Gives a concrete prerequisite for input (get todo list IDs from basecamp_get_todoset) and routes the group case to basecamp_move_todolist_group, which is a real exclusion. It stops short of clarifying reorder vs. move versus basecamp_reorder_todos, so it is clear context without full alternative coverage.

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-destructive, idempotent behavior. The description adds important domain context: groups always render after ungrouped todos, and the cross-list restriction. It doesn't mention pagination or return format, but these are less critical here.

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

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

Three sentences, each earning its place: the action, a rendering constraint, and a tool reference plus a hard limitation. Front-loaded with the core operation, no filler.

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

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

For a move operation with full schema and annotations, the description covers the essential constraints and where to get IDs. It could briefly mention that the operation affects ordering only, but is nearly 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 documents parameters thoroughly. The description adds the rule about using basecamp_list_todos for IDs, which is useful, but doesn't add much beyond the schema's own placement semantics. Baseline 4 is reasonable given the high schema quality and the small added guidance.

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

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

The description states a specific verb (move) and resource (todo list group/section), and clarifies the scope: 'to a different place among the groups of its todo list.' It distinguishes from basecamp_move_todolist, but doesn't explicitly name it as the sibling to avoid, leaving some differentiation implicit.

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

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

It gives a clear usage constraint ('You cannot move a group to a different todo list') and points to basecamp_list_todos for obtaining group IDs, which is helpful. However, it doesn't explicitly state when to prefer this tool versus basecamp_move_todo or basecamp_update_todolist_group (not a sibling), so alternative routing is only partially 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 declare idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds non-obvious behavioral requirements: only non-complete todos should be included, and all of them must be supplied in the new order, plus the group/list scoping quirk.

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

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

Four short sentences, front-loaded with the action, then the constraint, then the alternative tool, then the group caveat. Every sentence carries distinct, non-redundant information.

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

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

For a two-parameter reorder tool with full schema coverage and clear annotations, the description covers the operation, the ordering requirement, the alternative tool, and the group/list distinction. No output schema exists, but the effect (a reordering) is self-evident, so little is left hanging.

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 are already documented. The description reinforces that todo_ids is the complete set of incomplete todos in new order and that parent_id may be a list or a group, but adds no format or syntax beyond the schema.

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

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

States a specific verb and resource ('Set the order of all the todos in a todo list or in a group') and explicitly contrasts itself with basecamp_move_todo for single-todo moves. An agent can distinguish it from siblings without opening anything else.

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?

Gives explicit when-to-use ('sort todos, for example by due date'), names the alternative for a different case ('To move one todo, use basecamp_move_todo'), and disambiguates the group-vs-list case with the rule for which ID to pass.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the cascade effect ('The items in it come back too, for example the todos of a todo list'), which the annotations do not convey and which materially affects the outcome of the call.

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 short sentences, front-loaded with the core action, then the cascade side effect, then the lookup guidance. Every sentence carries distinct information and none is redundant with the schema or annotations.

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

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

For a single-parameter restore operation with no output schema, the description covers the action, the side effect on child items, and how to source the ID. It does not mention permissions, error cases (e.g., restoring an item that was never trashed), or what the response contains, but nothing essential to invoking it correctly 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?

With one parameter at 100% schema description coverage the baseline is 3, but the description adds value by explaining where the recording_id value comes from (basecamp_list_recordings with status 'trashed'). It does not clarify type/format details, but the sourcing guidance is a real addition beyond the schema's 'ID of the item to restore'.

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 concrete verb and resource ('Bring an item back from the trash or from the archive'), which is unambiguous and clearly the inverse of the sibling basecamp_trash. An agent can distinguish this tool from basecamp_list_recordings or basecamp_trash without inspecting any schema.

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

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

It gives a clear operating context and a concrete route to the prerequisite data: use basecamp_list_recordings with status 'trashed' to obtain valid IDs. It does not explicitly state when-not to use it (e.g., that untrashed items need no restore), so it falls just short of full when/when-not/alternatives coverage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true. The description adds real substance beyond that: cascade deletion of contained items (todos inside a trashed list), Basecamp's deferred permanent purge, and restoration via basecamp_restore with the same ID preserved. Only the retention timeframe remains unspecified ('after some time').

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

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

Three sentences, front-loaded with the action and its scope. The long type enumeration is justified because it defines applicability, though 'The items in it go too, for example the todos of a todo list' is slightly redundant with the preceding list.

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

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

For a single-parameter destructive mutation with full annotation coverage and no output schema, the description supplies everything needed: what it accepts, that deletion cascades, that removal is deferred and recoverable, and which tool undoes it. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% for the single recording_id parameter, so the baseline is 3. The description goes further by clarifying that the ID is polymorphic across nine distinct entity types, which meaningfully expands what an agent understands recording_id can accept.

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

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

States a specific verb+resource ('Move an item to the trash') and enumerates exactly which Basecamp entity types qualify (todo list, group, todo, message, comment, document, folder, upload, kanban card). This lets an agent determine applicability without consulting siblings.

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

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

Clearly scoped to trashing, and it names basecamp_restore as the recovery path, which implicitly tells the agent when this action is reversible. It does not, however, contrast this tool with alternatives like basecamp_move_todo or basecamp_update_* or state any precondition (e.g. permissions).

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?

Annotations cover the safety profile (destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description is free to add context — and it does: mentions trigger notifications, an invalid person ID "returns an error and writes nothing," and bc-attachment tags are auto-enriched on save and auto-collapsed before content operations run. This is meaningful behavior beyond the annotations, though permission/ownership constraints are unmentioned.

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 purpose and the partial-operation tip are front-loaded, and the HTML reference is broken into scannable bullets rather than prose. It is long, but nearly every bullet carries a rule required for a valid call (paragraph wrapping, mention syntax, attachment sgid sourcing), so the size is largely earned.

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 rich-content mutation tool with no output schema, the definition supplies the formatting contract, the mention/attachment mechanics, and error behavior, which is the hard part of calling this correctly. It stops short of describing the return payload and any permission or existence requirements for comment_id, leaving small gaps.

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 three exclusive modes (content vs content_append/content_prepend/search_replace) are already documented in the schema, giving a baseline of 3. The description earns above baseline by adding a preference rule for partial operations and, critically, by specifying the HTML dialect that the `content` string must conform to — semantics the schema cannot express.

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 gives a clear verb+resource ("Update a comment"), which is self-evident against the update/create family of siblings. However, it never explicitly contrasts with the closely related basecamp_create_comment or basecamp_list_comments, so sibling differentiation relies on the reader's inference from the verb alone.

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

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

"Use partial content operations when possible to save on token usage" is genuine guidance on which parameter mode to prefer, and the HTML rules implicitly define the expected input context. But there is no explicit when-to-use/when-not versus siblings, and no statement of prerequisites such as the comment needing to exist or permission requirements.

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 the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description goes beyond that by disclosing non-obvious behavior: bc-attachment tags are auto-enriched on save, existing enriched tags are auto-collapsed before append/prepend/search_replace, and an invalid person ID causes an error with no write. Auth/permission requirements and the reversibility of full content replacement are not addressed.

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?

Purpose and the token-saving hint are front-loaded, then the formatting rules follow. The block is long, but for a tool whose core job is emitting valid HTML the rules are substantive rather than filler; a few explanatory asides could still be tightened.

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 could say more about the response, and it omits permission requirements. However, for a complex HTML-content mutation it covers the critical ground: format rules, attachment handling, error behavior, and the mutual exclusivity implied by the modes.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds substantial meaning beyond the schema by defining the exact HTML dialect required for the content parameters (allowed tags, paragraph rules, bc-attachment usage, highlight variables), which the schema does not provide and which is essential to invoking the content fields correctly.

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

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

States a clear verb+resource ("Update a document") and the name reinforces it. It does not, however, distinguish itself from siblings like basecamp_update_message or basecamp_create_document, so the agent gets no explicit routing signal beyond the name itself.

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

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

"Use partial content operations when possible to save on token usage" gives guidance on choosing among the content/content_append/content_prepend/search_replace modes, which is useful. But there is no when-to-use/when-not guidance relative to sibling tools, and no prerequisites or exclusions for the tool as a whole.

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?

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by disclosing error behavior ('If the ID is not a person, the tool returns an error and writes nothing'), server-side auto-enrichment of bc-attachment tags, and the automatic collapsing of enriched tags before append/prepend/search_replace so callers don't strip manually. It does not warn that the steps array is a full replacement whose omissions are deleted, which is the main destructive behavior of this tool.

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

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

Purpose, precondition, and the token-saving tip are correctly front-loaded, and the bulleted HTML list is scannable. However, the HTML reference is roughly ten bullets of format documentation that dwarf the actual update semantics, and parts (color index table, gallery syntax) are reference material rather than decision-relevant 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?

For a 9-parameter mutation tool with nested step objects and no output schema, the description covers the hardest thing to get right (valid HTML content format) thoroughly and names the helper tools for IDs and attachments. The notable omission is that replacing 'steps' silently deletes steps not resent, which an agent should be warned about before calling.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the full allowed HTML tag set, required paragraph wrapping and <p><br></p> separator rules, mention/gallery syntax, and the highlight variable convention. The mutual-exclusion rules are restated from the schema rather than extended.

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

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

States a specific verb and resource immediately: 'Update a kanban card including its steps.' This is clearly distinguishable from the adjacent siblings create_kanban_card, move_kanban_card, get_kanban_card, and list_kanban_cards without opening any schema.

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

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

Provides a hard precondition ('At least one field must be provided') and a clear preference rule ('Use partial content operations when possible to save on token usage'). It also routes the agent to basecamp_list_people, basecamp_list_recordings, and basecamp_create_attachment for the supporting data HTML needs. It never states when to use this instead of basecamp_move_kanban_card or basecamp_update_todo, so exclusions are absent.

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

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

Beyond the annotations, the description discloses rich behavioral detail: HTML tag restrictions, paragraph handling, mention-side effects (notification, error-and-no-write on invalid person IDs), attachment auto-enrichment, automatic collapsing of enriched bc-attachment tags before partial operations, and the absence of an <img> tag. This is exactly the kind of context an agent needs before mutating message content.

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 it is front-loaded with the core operation and then organized into a clearly labelled HTML-rules bullet list. Most rules earn their place for an agent writing Basecamp-compatible HTML, though the volume of formatting detail makes it less concise than an ideal tool description.

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 complex mutation tool with seven parameters, 100% schema coverage, no output schema, and annotations that only cover safety hints, the description completes the missing operational picture. It covers content editing modes, HTML formatting, mentions, attachments, error behavior, and automatic normalization, leaving no major agent-facing 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the content-related parameters by explaining allowable HTML, the need for <p> wrapping, attachment sgid sourcing, and mention syntax. It does not add much beyond the schema for subject, message_id, or message_type_id, so it lands above baseline but not at the top.

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

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

The description opens with a specific verb and resource: 'Update a message.' An agent can identify this as the message-update operation. However, it does not explicitly distinguish this tool from siblings like basecamp_update_comment or basecamp_update_document, so sibling differentiation is left to the resource name.

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

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

The description advises using partial content operations to save tokens, which is useful guidance for choosing among content/content_append/content_prepend/search_replace. It does not say when to use this tool versus basecamp_create_message or basecamp_update_comment, nor does it mention prerequisites such as needing the message_id or permission context.

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 cover the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds genuine behavior beyond that: mentioning a person sends them a notification, an invalid person ID makes the tool error and write nothing (atomicity), Basecamp auto-enriches bc-attachment tags after saving, and enriched tags are auto-collapsed before append/prepend/search_replace runs. It stops short of stating permission requirements (e.g. whether the caller must be an assignee or project member).

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?

Purpose is front-loaded in the first two sentences, which is good, but roughly 90% of the text is a generic HTML style guide rather than information specific to updating a todo. It is dense and mostly earns its place, yet it displaces update-specific semantics (partial-update behavior, assignment semantics) with formatting minutiae.

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?

There is no output schema, so return values need not be explained, and the annotations carry the safety/idempotency profile. Combined with a 100%-documented schema, the description supplies what structured fields cannot: content markup rules, atomic error behavior, notification side effects, and the auto-collapse/auto-enrichment behavior an agent must plan around.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters and the content/content_append/content_prepend/search_replace mutual exclusions. The description nonetheless adds meaning the schema cannot carry: the full HTML grammar required for content values, the required <p><br></p> paragraph separator, and the bc-attachment/person/gallery markup with where to source sgids and person IDs — real construction guidance for the most error-prone 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 opening sentence gives a specific verb and resource: 'Update a todo item.' An agent knows this is a mutation on an existing todo. However, it never distinguishes itself from near-neighbors like basecamp_complete_todo, basecamp_move_todo, basecamp_uncomplete_todo, or basecamp_update_todolist, so sibling routing is left to inference.

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

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

There is one real usage directive: 'Use partial content operations when possible to save on token usage,' which steers between content and content_append/prepend/search_replace. But there is no guidance on when to use update_todo versus complete/move/reorder tools, no prerequisites (project/todolist context), and no statement of what happens to fields that are omitted.

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 substantial behavior beyond the annotations: person mentions trigger notifications, an invalid person ID makes the whole write fail atomically, bc-attachment tags are auto-enriched on save and auto-collapsed before partial ops, and external images must be uploaded first (no <img> support). These side-effect and error semantics are exactly what the description should carry on top of readOnly=false/idempotent=true.

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?

Purpose is front-loaded and the HTML rules are bulleted, but the description is a very long wall of reference text with some redundancy ('you never need to write those', 'you don't need to strip it yourself yourself'). Most rules are load-bearing for correctness, yet the sheer length and overlap keep it from being tight.

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 no output schema, it comprehensively covers content formatting, error behavior, and attachment handling, which is what an agent needs to call it without producing malformed content. It stops short of describing the response shape or any permission/auth requirements.

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 already 100%, so the baseline is 3, but the description adds real semantics for content: the accepted HTML tag set, paragraph/heading/list/table conventions, mention and attachment syntax, and the token-saving rationale for append/prepend/search_replace. It goes beyond restating the schema fields.

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 opening sentence names a specific verb (Update) and resource (a todo list, or a group/section within it), and explicitly bounds scope by stating fields updated (name, description). It also distinguishes itself from completion-capable siblings with 'A todo list is complete when all its todos are complete, so this tool cannot complete it.' An agent can tell this apart from basecamp_update_todo, basecamp_complete_todo, and basecamp_move_todolist.

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?

Gives clear operational guidance: prefer partial content operations (append/prepend/search_replace) over full replacement to save tokens, and warns that any invalid person ID causes the tool to write nothing. It does not explicitly route the agent between this tool and alternatives like basecamp_move_todolist or basecamp_create_todolist_group, so it stops short of full when/when-not framing.

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.