handoff-mcp-server

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

With no annotations, the description must convey behavioral traits. 'Claim' implies a state change, but the description does not specify effects like assigning the handoff to an agent, locking, or side effects. It lacks details on permissions, reversibility, or response behavior.

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

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

The description is a single short sentence, which is concise but to the point of being insufficient. It earns its place by stating the action but lacks necessary elaboration. Structure is adequate, but brevity compromises completeness.

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 complexity (2 required params, no annotations, no output schema) and sibling tools, the description is incomplete. It does not explain the return value, the effect on the handoff state, or how to integrate into a handoff workflow. Annotations or more detail are 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 0%, and the description does not explain the purpose of 'id' and 'agent_id'. While 'id' likely refers to the handoff identifier and 'agent_id' to the claiming agent, this is not stated. The description fails to add meaning beyond the schema's existence of parameters.

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

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

The description 'Claim an open handoff' uses a specific verb and resource. It clearly indicates the action on the 'handoff' entity and distinguishes from siblings like 'handoff_create', 'handoff_complete', and 'handoff_list'. The purpose is clear, though the term 'claim' could benefit from more context.

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 does not indicate when to use this tool versus alternatives (e.g., 'handoff_create' vs 'handoff_claim'), nor does it mention prerequisites, such as the handoff must be open or the agent must be authorized. This is a critical omission for a lifecycle tool.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It merely states the action without describing side effects, permissions, or state changes, which is insufficient for safe invocation.

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 short (one sentence), but this conciseness comes at the cost of completeness. Essential information about parameters and behavior is missing, making it underspecified rather than 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 has three parameters, no output schema, and no annotations, the description fails to provide sufficient context. It does not explain what 'completing' a handoff involves, why the result and agent_id parameters exist, or what the outcome looks like.

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 0%, and the description does not explain the meaning or usage of any of the three parameters (id, result, agent_id). The agent has no information beyond the schema field types.

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 'Complete a handoff' specifies a verb and resource, distinguishing it from sibling tools like handoff_create or handoff_list. However, it lacks details on what 'complete' entails, making it only moderately clear.

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 handoff_get or handoff_claim. The description does not provide context for when a handoff should be completed.

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 present, and the description does not disclose behavioral traits such as idempotency, required permissions, or side effects. The burden falls entirely on the single-line description, which is insufficient.

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 only three words long, which is under-specified for a tool with multiple parameters and no annotations. It sacrifices essential information for brevity.

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 (7 parameters, no annotations, no output schema), the description is woefully incomplete. It fails to provide any context about return values, error states, or interrelation with sibling tools.

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 0%, and the description provides no additional meaning for any of the 7 parameters. The agent must rely solely on the schema names, which for 'context', 'tags', or 'ttl_minutes' are ambiguous.

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 'Create a durable handoff' clearly states the action and resource. It differentiates from sibling tools like handoff_claim and handoff_complete by implying creation, though it does not define 'handoff'.

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 handoff_claim or handoff_complete, nor any prerequisites or context for when a handoff should be created.

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 exist, and the description does not disclose any behavioral details such as whether the operation is read-only, idempotent, or what happens if the handoff doesn't exist. The minimal text provides no transparency beyond the basic 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?

The description is extremely short (3 words), which is concise but at the cost of useful information. It is front-loaded but lacks substance, making it minimally viable.

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

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

Given no output schema and limited sibling context, the description fails to specify what a handoff is, what the return value contains, or any prerequisites. The tool is under-documented for effective use.

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

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

The schema has 0% description coverage, and the description does not explain the 'id' parameter beyond its name. No information is given about what constitutes a valid id or how to obtain it.

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

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

The description 'Get one handoff' clearly indicates the action (retrieve) and resource (handoff). It distinguishes from handoff_list by implying a single item, but does not explicitly differentiate.

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

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 handoff_list or handoff_get for specific scenarios. The description lacks usage 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?

No annotations provided, and the description fails to disclose behavioral traits such as ordering, pagination, side effects (read-only vs. mutating), or whether results are scoped to a user/workspace. The agent must guess behavior from the schema alone.

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, which is concise, but it is overly terse and fails to provide essential context. Front-loading is not an issue, but the content is too sparse to be useful.

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, no annotations, and 3 undocumented parameters, the description is completely inadequate. It omits return format, default behavior, error conditions, and any other context needed for correct invocation.

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

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

Schema has 0% description coverage for its 3 parameters (status, agent_id, include_completed). The tool description adds no explanations or constraints, leaving the agent to infer meaning from parameter names only.

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 the verb 'List' and resource 'durable handoffs', but does not differentiate from sibling tools like handoff_get (which likely retrieves a single handoff) or scratchpad_list. The word 'durable' is ambiguous without context.

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 over alternatives such as handoff_get, handoff_claim, or scratchpad_list. The description lacks prerequisites, filtering hints, or use case 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?

With no annotations, the description should disclose behavioral traits like permanence, side effects, or required permissions. It only states 'Delete scratchpad entry,' leaving the agent unaware of deletion implications (e.g., irreversible, no return 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?

The description is a single short sentence, which is concise but lacks any structure. While it saves tokens, it omits critical information that could be included without significant length, such as parameter explanations.

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 annotations, no output schema, and limited parameter documentation, the description is inadequate. It does not explain what a scratchpad entry is, what the 'key' represents, how 'agent_id' is used, or what happens upon success or failure.

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 0%, and the description does not explain the parameters 'key' or 'agent_id.' The agent cannot infer their meaning or usage from the description alone, which adds no value beyond the schema.

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

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

The description 'Delete scratchpad entry' clearly states the action (delete) and resource (scratchpad entry). It directly distinguishes from sibling tools like scratchpad_get, scratchpad_list, and scratchpad_set, which have different purposes.

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

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 using scratchpad_set to overwrite an entry or scratchpad_get to retrieve it. There are no prerequisites or contextual hints.

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 present, so the description carries full burden. It only states the basic operation (get) without disclosing behaviors like what happens if the key is missing, whether the operation is read-only, or any side effects. Minimal 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 extremely concise at three words, but it sacrifices necessary detail. It is not informative enough to earn its place; under-specification outweighs brevity.

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 a simple tool with no output schema and no annotations, the description should cover usage, parameter meaning, and return behavior. It only states the basic action, leaving the agent with insufficient context 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?

The input schema has two parameters (key, agent_id) with 0% description coverage. The description does not explain the meaning or usage of either parameter, failing to add any value beyond the schema.

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

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

The description 'Get scratchpad value' clearly identifies the verb (get) and resource (scratchpad). It differentiates from siblings like scratchpad_set (set) and scratchpad_delete (delete). However, it does not mention that the retrieval is by key, which is only inferred from the 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?

No guidance is provided on when to use this tool versus alternatives like scratchpad_list or scratchpad_set. The description lacks context for choosing this tool over related ones.

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 must convey behavioral traits. It only says 'list', which implies a read operation, but fails to disclose details like whether it returns all entries or supports filtering, pagination, or ordering. No mention of side effects or permissions.

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

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

The description is concise at one sentence, but it lacks substance. It is not overly verbose, but the brevity sacrifices clarity and usefulness. It could be considered appropriately concise if it included more information, but as is, it is too sparse.

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 two parameters and no output schema, the description is incomplete. It does not explain how the parameters affect results, what the output format is, or any limitations. The description fails to provide a complete picture for effective use.

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

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

Schema description coverage is 0%, so the description should explain the parameters. The parameters 'prefix' and 'agent_id' are not explained. The description adds no meaning beyond the schema's property names, which are ambiguous without context.

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 scratchpad entries' clearly states the action (list) and resource (scratchpad entries). It distinguishes from sibling tools like scratchpad_get (single entry) and scratchpad_delete/scratchpad_set (write operations). However, it could be more specific about optional filtering.

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. For example, it does not mention that scratchpad_get retrieves a single entry, or that scratchpad_list is for listing with optional filters. The description lacks context for selecting this tool.

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

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

With no annotations, the description should disclose behavioral traits, but it only says 'durable,' implying persistence. It does not mention overwrite behavior, authorization needs, or side effects like visibility and TTL handling.

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 brief (4 words), which is concise but at the expense of necessary detail. It lacks context that could be added without verbosity.

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

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

Given the 5 parameters, no output schema, and no annotations, the description is wholly inadequate. It fails to explain return values, error conditions, or the role of visibility and TTL, making it nearly useless for an agent.

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

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

The input schema has 5 parameters with 0% coverage, and the description adds no meaning for any parameter. Terms like 'key,' 'value,' 'agent_id,' etc., are left undefined.

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 'Set' and the resource 'durable scratchpad value,' distinguishing it from sibling tools like scratchpad_delete and scratchpad_get. However, it does not differentiate between setting a new value and updating an existing one.

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. There is no mention of prerequisites, best practices, or exclusions, leaving the agent without context for proper selection.

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