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

With no annotations, the description carries the disclosure burden. It reveals a key behavioral constraint: 'Requires editor role on the motion' and the dependency on get_motion. It stops short of explaining side effects or reversibility, but the essential context is provided.

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, front-loaded with the purpose, followed by role and usage. Every sentence earns its place with no 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 simple action, the description covers purpose, permission, and prerequisite. The schema fully documents parameters. It lacks an explicit mention of return values or post-approval effects, but the tool's simplicity makes the information sufficient.

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 all parameters are described in the schema. The description adds a workflow tip about using get_motion, but no additional parameter-specific semantics beyond what the schema already provides.

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

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

The description states 'Approve a plan step on a motion' with a specific verb and resource, clearly distinguishing it from sibling tools like 'reject' and 'comment'. The purpose is immediately obvious.

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 instructs to 'Use get_motion first to see the plan and identify the step_index (0-based)', establishing a clear prerequisite and workflow. It doesn't list alternatives, but the action is specific enough that the guidance is effective.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: privacy ('private message') and synchronous response ('returned directly'). However, it does not state whether the operation is read-only, what permissions are required, or any potential side effects, which leaves some ambiguity for a tool lacking annotation support.

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 exactly two sentences, front-loaded with the core action and supplemented by important privacy/delivery details. No redundant or tangential 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 tool with only 3 parameters and no output schema, the description covers the essential context: what it does, the motion scope, privacy, and that the response is returned directly. A minor gap is the lack of detail about the response format, but this is acceptable for a straightforward Q&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?

Schema description coverage is 100%, so the baseline is 3. The description adds minor context by implying the 'question' parameter is private and the 'motion_short_id' ties to a specific motion, but it does not add significant meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's function: 'Ask Monnet a question in the context of a specific motion.' It uses a specific verb ('Ask') and resource ('Monnet') and notes the motion context, distinguishing it from sibling tools like 'comment' (public) and 'get_motion' (retrieval).

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

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

The description gives clear context for when to use the tool: when asking Monnet a question about a specific motion, and it notes that the message is private ('only you and Monnet see it'). It does not explicitly name alternatives or exclusions, but the context is sufficient to differentiate from public commenting.

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?

No annotations are provided, so the description carries the full burden. It discloses the user-approval requirement before posting, notes that nothing is posted without explicit confirmation, and mentions that Monnet may respond. This covers the main side effects and permission aspects, though it doesn't address other potential behaviors like edit/retraction.

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 clear, well-structured sentences. The first sentence states the purpose and usage pattern; the second covers the approval workflow and response behavior. No wasted words.

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

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

The description is self-sufficient for a tool with no output schema and no annotations. It covers the purpose, thread depth rule, approval mechanism, and potential Monnet response, providing all necessary context for safe and effective use.

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

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

The input schema already provides detailed descriptions for all parameters (100% coverage), including the parent_id thread-depth constraint. The description adds little beyond the schema for parameter meaning, meeting the baseline for high schema coverage.

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

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

The description clearly states a specific action ('Post a public comment on a motion') and differentiates between top-level and reply comments. It distinctly positions the tool relative to siblings like approve/reject and ask_monnet.

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

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

The description provides clear context on when to use the tool (posting a public comment) and how to use it for both top-level and threaded replies. It does not explicitly name alternatives or exclusion cases, but context is unambiguous.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains the asynchronous nature (returns immediately while a background Monnet run drafts the full motion) and the return values (id and URL). It does not cover error conditions or permission requirements, which is a minor gap.

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, front-loaded sentences cover purpose, behavior, and follow-up instructions. There is no filler or 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?

The description fully covers the creation flow, including the async drafting process and how to retrieve the result via get_motion. Even without an output schema, it provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, with both parameters already well-described in the schema. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states 'Create a new draft motion in a Monnet workspace from a free-form prompt' with a specific verb and resource, distinguishing it from sibling tools like get_motion and update_motion. It also specifies the immediate return of id and URL.

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

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

The description implies the tool is for creating new motions and instructs the agent to call get_motion with the returned short_id to inspect the draft. However, it does not explicitly state when not to use it or mention alternative tools for different scenarios.

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

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

With no annotations, the description carries the transparency burden. It discloses the scope (all workspaces) and categories of content (pending approvals, unread activity, assigned steps), which is useful. However, it does not explicitly state that this is a read-only operation, nor does it mention sort order, side effects, or error behavior, leaving meaningful gaps.

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 the action and resource, then the trigger phrases. Every clause adds value and there is no fluff or repetition of schema details.

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

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

The tool is simple with optional pagination only. The description explains what the feed contains and when to use it, which is mostly complete given the rich schema. It does not describe the exact return shape or pagination metadata, but with no output schema and simple list semantics, this is a minor gap.

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

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

Schema description coverage is 100%, so the params page and limit are already well documented. The description adds no additional parameter meaning beyond what the schema provides, placing this at the baseline score of 3.

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

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

The description uses a specific verb ('Fetch') and clearly identifies the resource ('user's 'For You' feed') with concrete contents (pending approvals, unread activity, assigned steps). It is easily distinguished from sibling tools like list_motions, which would list motions more generally, and approve/reject, which are individual 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?

Explicitly provides when-to-use triggers: 'Use this when the user asks 'what's on my plate', 'what needs my attention', or similar.' It gives clear context for usage but does not mention when NOT to use it or point to alternatives, so it misses the highest bar.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is a read ('Read'), enumerates the returned data structure, and adds a behavioral nuance: comment short ids are usable as parent_id in the comment tool. It does not discuss auth, rate limits, or error cases, but for a read tool this is reasonable.

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: the first is information-dense but front-loaded with the core action; the second adds a usage trigger and a helpful cross-tool detail. No redundant phrasing exists.

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 purpose, usage context, and return content, and even includes a pointer to the comment tool's parent_id. Given the tool's simplicity (2 params, no output schema), this is nearly complete. It lacks an explicit statement about non-mutating behavior, but 'Read' already implies it.

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

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

The input schema already provides 100% coverage for both parameters with detailed descriptions. The tool description adds no new parameter semantics beyond indicating lookup by short id or URL, which is already implied by motion_short_id's schema. Therefore the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Read') and explicitly lists the resource ('a Monnet motion's full details') and the key content fields (summary, body, status, priority, plan steps, member roles, threaded comments). This clearly distinguishes it from sibling tools like list_motions, which would list motions rather than fetch one motion'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 provides an explicit usage trigger: 'Call this when the user references a specific motion by its short id or URL.' It does not mention alternatives or when not to use it, but the context is clear enough for an agent to select it over list_motions or other 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?

With no annotations, the description carries the full burden. It discloses that MEMORY.md is 'concise, auto-synthesized', 'distilled from closed motions', and that it contains priorities and decisions. This gives useful behavioral context about the nature of the returned content, though it doesn't mention return format or error conditions.

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

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

Two sentences, no fluff. The first sentence defines what the tool does, the second gives usage guidance. Every word serves a purpose.

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

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

For a tool with one parameter, no annotations, and no output schema, the description is quite complete: it explains what the tool returns (a digest of workspace context) and why to use it. It could explicitly state that the full MEMORY.md content is returned, but the word 'Read' strongly implies that.

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 one parameter (workspace_slug) is well described in the schema, including advice to call list_workspaces first. The description adds no additional parameter information, so the 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 starts with a specific verb and resource: 'Read a Monnet workspace's MEMORY.md'. It clearly distinguishes itself from sibling tools by explaining that this is a distilled digest of workspace context, not a motion or inbox item.

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

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

It explicitly says 'Use it to ground yourself in what the team already cares about and has decided', providing a clear when-to-use. It also implies an alternative ('without re-reading every motion') though it does not name sibling tools like get_motion or list_motions as 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?

With no annotations, the description carries the burden. It discloses that it returns short ids (not full motion data) and defaults to 'open' status, which adds behavioral context. However, it does not explicitly state read-only safety, pagination behavior, or response shape, leaving gaps.

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

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

The description is compact with three sentences, each providing distinct value: purpose, follow-up behavior, and default filter. No wasted words and important information is front-loaded.

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

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

Given no output schema, the description hints at the return shape (short ids) but doesn't fully specify the response structure. However, the tool is relatively simple and the schema covers all parameters, making the description largely sufficient for an AI to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds little beyond the schema: it mentions filterable by status and default status open, both already in schema. It does not clarify parameter syntax or add 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 the tool lists motions in a workspace and is filterable by status. It also distinguishes itself from get_motion by mentioning short ids for follow-up, which is a specific resource and action.

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

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

It provides clear context that this is for listing and mentions using get_motion for a specific motion, but doesn't explicitly state when not to use this tool or compare with other listing alternatives. The implicit guidance is adequate but not fully explicit.

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

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

With no annotations, the description carries the transparency burden. It discloses scope ('workspaces you are a member of') and return details (name and slug), which goes beyond the obvious 'list' verb. However, it doesn't explicitly state potential behaviors like pagination or empty list handling, but for a simple read-only tool this is acceptable.

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

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

Two sentences, front-loaded with the main purpose, and the second sentence explains why this tool matters. Every word earns its place; no fluff or repetition of schema fields.

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 parameterless list tool with no output schema, the description is fully adequate. It covers what the tool does, what it returns, and when to call it. There are no missing pieces given the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The baseline for 0-parameter tools is 4. The description doesn't need to explain parameters and instead adds value by describing the output, which aligns with 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 clearly states the tool's function: 'List all Monnet workspaces you are a member of.' It uses a specific verb and resource, and adds valuable context by noting it returns the workspace slug needed by other tools, distinguishing it from siblings like get_workspace_memory.

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

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

Provides explicit guidance: 'Call this first if you don't know the workspace slug.' This tells the agent when to use the tool relative to others and frames it as a prerequisite for tools like get_motion and list_motions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions verifying the connection and listing API keys, which implies read-only behavior and possible exposure of sensitive data, but it does not explicitly state that no modifications occur or describe what happens on failure. More detail could improve 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 two short sentences, front-loaded with actionable verbs. Every word contributes meaning: 'Verify', 'list', 'debugging setup issues'. There is no waste or redundancy.

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

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

For a zero-parameter diagnostic tool with no output schema, the description is remarkably complete. It states the purpose, the specific actions, and the ideal use case. No further details are necessary for an agent to decide when and how to invoke it.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly avoids mentioning parameters, and the input schema (empty properties) aligns with the described functionality. No additional parameter semantics are needed.

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 two specific verbs: 'Verify your Monnet MCP connection' and 'list the API keys on your account', which clearly identifies the tool as an identity/connection check. This distinguishes it from siblings like list_workspaces and get_motion, which operate on different resources.

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 states 'Useful for debugging setup issues', giving a clear scenario for when to use the tool. While it doesn't explicitly exclude alternatives or mention when not to use it, the context is sufficient for a diagnostic tool of this nature.

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

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

With no annotations provided, the description must carry the full disclosure burden. It does reveal that editor role is required, which is useful. However, it does not disclose side effects such as whether the rejection is permanent, notifications triggered, or changes to motion state. This is a partial disclosure but lacks key 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?

The description is two sentences, with the first stating the purpose and the second providing permission and prerequisite context. It is front-loaded, concise, and every sentence adds meaningful 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?

The tool is a mutation with no output schema and no annotations. The description covers purpose, permission, and prerequisite, but omits return value/response behavior and any side effects. It is reasonably complete for invoking the tool but lacks full context that would help an agent anticipate the outcome.

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

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

The input schema already has detailed descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds marginal value by advising to use get_motion first to identify step_index, which is practical guidance, but it does not provide new parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: 'Reject a plan step on a motion, with an optional reason.' This uses a specific verb (reject) and resource (plan step on a motion), distinguishing it from sibling tools like approve and comment. It also implies the scope of the action (a single plan step).

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

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

The description provides clear usage context: 'Requires editor role on the motion' and 'Use get_motion first to see the plan and identify the step_index (0-based).' It tells the agent when the tool can be used and a necessary prerequisite, though it does not explicitly mention 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?

With no annotations provided, the description carries the full burden. It discloses two important behaviors: (1) all fields are optional, meaning only specified fields are changed (partial update), and (2) plan updates require sending the full replacement list, preventing accidental data loss. This goes beyond the schema and provides essential operational 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 two sentences with no wordiness. The first sentence states purpose and optionality; the second addresses the most complex parameter (plan) with actionable guidance. Front-loaded and 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 complexity (6 params, nested plan objects, no output schema), the description covers the key pitfalls: partial update semantics and the full-replacement requirement for plans. It doesn't mention return values, but no output schema exists and the description is otherwise sufficient for a mutation 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?

However, it adds meaningful context beyond the schema: it clarifies that fields are optional (only include what to change) and that plan is a full replacement rather than a merge. This helps an agent understand the 'behavior' of each parameter, complementing the 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 tool's function with a specific verb ('Update') and resource ('a motion'), listing the modifiable fields (summary, body, priority, or plan). This distinguishes it from sibling tools like create_motion (creation), get_motion (retrieval), and approve/reject (status 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?

The description provides clear context on when to use the tool (updating existing motion fields) and gives explicit instruction for plan updates: 'use get_motion first to see the current plan, then modify and send it back.' It does not explicitly name alternative tools or exclusions, but the usage pattern is clear enough for an agent.

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