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

No annotations exist, so description carries full burden. Discloses critical behaviors: content is auto-processed (entity/relationship extraction) and coherence warnings are surfaced. Does not mention error handling or permissions, but core behavioral traits are covered.

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

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

Three sentences front-loaded with main purpose, each sentence adds value. Could be slightly more structured with parameter details, but overall efficient and clear.

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 annotations, no output schema, and nested parameters, description is somewhat lightweight. Covers core purpose and behavioral traits, but fails to explain return behavior or parameter usage fully. Adequate for a simple creation tool but leaves 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 description coverage is 0%, so description must compensate but fails to. Does not explain the meaning of 'scope' (nested object with plan_id, goal_id, node_id), 'entry_type' enum values, or 'source_description'. Only 'content' is implied but not clarified.

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 starts with 'Record a knowledge episode,' clearly stating the main action. Lists specific use cases (after research, on decisions, discovering context) which differentiates it from sibling tools like recall_knowledge (retrieval) and others.

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 says when to use: after research, on decisions, or when discovering important context. Also mentions automatic entity extraction and coherence warnings, helping the agent understand context. Lacks explicit when-not-to-use or alternative tool names, but sufficient given the clear purpose.

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

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

The description lists the types of information returned (goal health, pending decisions, tasks, activity, recommendation) but does not disclose side effects, authentication needs, or rate limits. With no annotations present, the description provides basic behavioral context but lacks depth.

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: the first explains functionality, the second provides usage guidance. No redundancy, front-loaded with critical 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?

The description covers purpose and usage well but completely omits parameter semantics, which are needed for correct invocation given 4 optional parameters. Without an output schema, more detail on return values would also help. Adequate but with clear 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?

The input schema defines 4 parameters (scope, goal_id, plan_id, recent_window_hours) with 0% schema description coverage. The description does not explain the meaning, defaults, or valid values of any parameter, forcing the agent to infer from names alone.

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

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

The description clearly states the tool aggregates key mission control information in one call ('goal health summary, pending decisions, my tasks, recent activity, and a top recommendation'), and it positions itself as the single read for Cowork live artifacts, distinguishing it from siblings like goal_state or plan_analysis.

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 recommends using this as 'the single read for Cowork live artifacts and the autopilot's first call,' providing clear context for when to invoke it. However, it does not explicitly state when not to use it 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?

With no annotations provided, the description carries the full burden. It discloses the internal resolution order and the effect of the dry_run parameter. However, it does not cover error handling or authorization, but the disclosed logic is sufficient for an agent to understand the tool's behavior.

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

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

The description is extremely concise with only two sentences. The core action is front-loaded, and every sentence provides necessary information 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?

The tool is complex with 5 parameters and a nested scope object, yet no output schema. The description explains the resolution order and the fresh parameter, but omits details about the return value ('context'), the effect of context_depth, and edge cases like no task available. This leaves the agent with incomplete understanding.

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

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

Only 20% of parameters (dry_run) have descriptions in the schema. The description adds meaning for fresh and scope, but does not describe ttl_minutes or context_depth. It partially compensates for the low schema coverage but leaves gaps.

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 the verb 'Pick', 'claim', and 'return' applied to the resource 'next task'. The resolution order and the fresh parameter add specificity, making the tool's purpose distinct, even though it does not explicitly differentiate from sibling 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?

The description provides clear guidelines on the resolution order and when to use fresh:true to skip the resume step. It does not explicitly mention when not to use the tool or compare with alternatives like 'release_task', but the context is well-defined.

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

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

Discloses default status='active' and that draft status puts it in pending queue, and workspace landing behavior. With no annotations, description carries full burden and does well, though could mention if there are any side effects like notifications.

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 purpose, then usage guidance, then details. Every sentence provides distinct value, no fluff.

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

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

For a 7-param tool with no output schema, the description covers key behavioral aspects (top-level, defaults, workspace) and complements schema. Could be slightly more explicit about what 'top-level' means relative to a hierarchy, but overall complete enough.

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 86%, and the description adds value by explaining default behaviors for status and workspace, which aren't fully captured in schema descriptions. But it doesn't elaborate on success_criteria or priority 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?

The description clearly states 'Create a new top-level goal' with specific verb and resource, and distinguishes from sibling 'derive_subgoal' which creates subgoals under an existing goal.

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 says when to use (when human asks to set up a goal) and when not (use derive_subgoal for subgoals), plus details on defaults and optional workspace.

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, so description carries full burden. It discloses slug auto-generation and deduplication, which is helpful, but does not disclose other behavioral traits like authorization requirements, idempotency, or side effects beyond creation.

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, front-loaded sentences with no waste. First sentence states action and return; second adds crucial detail about slug behavior.

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

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

For a creation tool with no output schema, it covers key aspects: what is created, what is returned, and a notable behavior. Lacks detail on optional parameters and error conditions, but sufficient for typical 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 coverage is 40% (only icon and slug have schema descriptions). The description adds value by explaining slug auto-generation, but does not clarify the meaning of organization_id or title beyond what is obvious from context. Required parameters lack elaboration.

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 it creates a new workspace inside an organization and returns the row. The verb 'create' and resource 'workspace' are specific and distinguish from sibling tools like list_workspaces or update_goal.

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?

Implies usage when you want to create a workspace in an organization, but provides no guidance on when to use alternatives or prerequisites. No mention of when not to use this tool.

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

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

Discloses key behaviors: soft-delete (not permanent), cascading default, recoverability. No annotations provided, so description carries burden. Could mention authorization or side effects, but covers core 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?

Three efficient sentences, each adding value. Front-loaded with primary action. No redundant 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?

Covers core purpose and recovery, but lacks description of return value and does not fully document all parameters. With low schema coverage and no output schema, description could be more 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 25% (only plan_id described). Description adds context for cascade_children and implies node_id, but does not explain reason parameter. Partial compensation for low 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?

Clearly states 'soft-delete a node', specifying the verb and resource. Distinguishes from siblings like delete_plan (deletes plan) and update_node (updates node).

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 context: cascades to children by default and is recoverable. Gives recovery method via update_task. Doesn't state when not to use but offers enough guidance for an agent.

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 the soft-delete behavior and recoverability. However, it could mention potential side effects like cascading effects or permissions, but for a simple tool it 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 two sentences, front-loaded with the core action, and every word adds value. No redundancy or unnecessary 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?

Given the tool's simplicity (2 params, no output schema), the description covers the key aspects: what it does, recovery, and hard delete. Minor gap: no mention of return value or success indicator, but not essential.

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

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

Schema coverage is 50% (reason has a description). The description does not add meaning to plan_id beyond the tool name, nor does it explain reason further. Baseline 3 is appropriate as schema already handles half.

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 (soft-delete), the mechanism (setting status='archived'), and the resource (plan). It distinguishes the tool from hard delete, providing a specific verb and resource.

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

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

The description explicitly provides recovery instructions via update_plan and warns against using this tool for hard delete, directing to REST API. It gives clear when-to-use and when-not-to-use 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?

No annotations present, so description carries burden. It discloses defaults (status='active') and side effects (drafts surface in dashboard pending queue). Missing details on permissions or impact on parent, but still adds significant 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?

Three sentences, no wasted words. First sentence states purpose, second gives alternative, third gives usage nuance. Excellent 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?

Given 8 parameters, high schema coverage, no output schema or annotations, the description covers purpose, alternative, status behavior, and pending queue. Lacks return value description, but overall sufficient for a creation 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 63% (high), so baseline is 3. Description adds value by explaining that rationale 'becomes the description' and 'surfaces in human review', and clarifies status usage. Does not explain all enums but compensates.

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

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

The description explicitly states 'Create a sub-goal under an existing parent goal' and distinguishes from 'create_goal' for top-level goals. The verb and resource are 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?

It explicitly says when not to use it ('For a new top-level goal, use create_goal instead') and provides conditional guidance for status ('pass 'draft' for autonomous loops').

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, so description carries full burden. It discloses the default status 'active' and the nature of adding children. However, it does not mention side effects like whether it overwrites existing children or requires specific 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?

Two efficient sentences front-load the purpose, then provide usage guidance and a default 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?

Description is complete for understanding the tool's purpose and usage. It does not explain return values or error handling, but given no output schema and straightforward action, this is acceptable.

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 75%, so baseline is 3. Description adds the default status but does not provide additional details for parameters beyond what schema already offers. Minimal value added over 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 the verb 'Add children' and the resource 'existing phase or task'. It distinguishes from the sibling tool 'queue_decision' by specifying when to use each.

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

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

Explicitly states when to use ('when an agent has implicit authority to decompose work') and when not to ('high-stakes structural proposals, use queue_decision'). Also notes the default status behavior.

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

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

Discloses that node statuses reset to not_started and lineage is recorded via forked_from_blueprint_id. However, with no annotations, it omits permissions, failure behavior, or side effects like overwriting existing plans.

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 with the action front-loaded. No redundant information. Slightly more detail could be provided without losing conciseness.

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 3 parameters and no output schema, the description covers the core behavior and parameter roles. It lacks details about error handling (invalid blueprint_id, non-existent workspace) and return values.

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 67% (blueprint_id missing description). Description adds context about blueprint meaning but does not specify format or uniqueness of blueprint_id. The title parameter is adequately explained.

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 (fork), the object (plan-scope blueprint), and the result (new plan in target workspace). It distinguishes from siblings like save_as_blueprint and create_plan by specifying the fork behavior.

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?

Implies usage for duplicating a blueprint's structure into a workspace, but does not explicitly state when to use versus alternatives (e.g., save_as_blueprint or create_plan). No when-not-to-use 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?

No annotations exist, so the description fully carries the burden. It explains inline ordering creates 'blocks' edges, response includes structure summary and warnings, and draft auto-promotes when work begins. This is rich behavioral 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 dense and front-loaded with purpose, but could benefit from structuring into bullet points for readability. It is not overly long but is packed with procedural detail.

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

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

Covers creation details, dependency definition, status behavior, and response warnings. Missing explicit return value specification (no output schema) and error handling, but sufficient for a creation tool given 7 params.

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 low (43%), but the description adds meaning for key parameters: status (active/draft context), rationale (surfaces in human review), and tree (ref/depends_on usage). It compensates partially for undocumented parameters.

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

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

The description clearly states the tool creates a plan with a phase/task tree in one call, specifying inline dependency ordering. It distinguishes from siblings like 'extend_intention' by emphasizing one-call creation and edge declaration.

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

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

Provides clear guidance on when to use draft vs active status based on loop type, and warns against shipping bare hierarchy. However, it does not explicitly exclude alternatives or mention when not to use this tool.

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

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

No annotations are provided, so the description must fully disclose behavior. It only describes the output, not side effects or safety guarantees. For a read-only tool, it should explicitly state it does not modify state.

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 that front-loads the purpose and then lists the key outputs. Every word adds value 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?

The tool is simple, but the description lacks explanation of the parameter and the format of the returned surface map. It adequately covers the when and what, but not the how or parameter details.

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 mention the 'user_role' parameter. The parameter has an enum and default, but its meaning is not explained, leaving the agent to infer.

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

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

The description clearly states the tool's purpose ('Onboarding for new agents') and specifies what it returns ('BDI tool surface map and recommended workflows'). It distinguishes itself from siblings, which are specific action tools like delete or update.

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 for new agents, providing clear context. It does not explicitly state when not to use or mention alternatives, but the intended usage is evident.

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 clearly labels the tool as a 'read' operation, implying no side effects. Without annotations, it provides good behavioral context, though it could explicitly confirm its read-only nature.

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 extraneous words. The first sentence states the core purpose, and the second lists replacements. Efficient and 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?

Given a single parameter and no output schema, the description covers all aspects it intends to retrieve. It could mention the output format but is still adequate for the agent to understand the tool's scope.

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 is goal_id, and the description clarifies it is used to identify the goal for the read. Despite 0% schema coverage, the description adds sufficient meaning, though a more detailed format hint would be better.

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 it is a 'comprehensive single-goal read' and lists the specific aspects covered (details, quality, progress, etc.). It explicitly names the tools it replaces, clearly distinguishing from 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?

The description indicates it replaces multiple tools, suggesting it should be used for a holistic read. However, it does not explicitly state when not to use it or mention any prerequisites or side effects.

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, so the description carries full burden. It discloses authorization requirement and 404 error case, but omits other behavioral traits like idempotency, rate limits, or what happens if user already a 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?

Two sentences efficiently convey the main action, authorization, and an important behavior. Front-loaded with the primary purpose, no wasted words.

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

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

It lacks description of return value (success response) and puts no detail on which parameter to prefer. Given the tool's moderate complexity (4 params, 1 required), it is adequate but not fully comprehensive.

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 0% schema coverage, the description adds meaning by explaining organization_id as required, user_id and email as alternative identifiers, and role with default. It lacks explicit enumeration of role options but covers core semantics.

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: 'Add a user to an organization by user_id or email.' It distinguishes from sibling tools like 'remove_member' and 'update_member_role' by specifying the invite action and methods.

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 specifies prerequisites: 'Caller must be org owner or admin.' It also explains the 404 behavior for non-existing email, indicating a limitation. However, it does not explicitly guide when to use user_id vs email or mention any 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?

No annotations provided; description carries full burden. States mutation ('Create'), cycle rejection, and same-plan constraint. Lacks details on persistence, permissions, or reversal. Adequate but could be richer for a mutation 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?

Three sentences, no fluff, front-loaded with purpose. Every sentence adds value. Ideal conciseness for a 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?

Covers basic purpose and key constraints (same plan, cycle rejection). Lacks details on error behavior, return values, or verification. With no output schema and no annotations, more completeness would be beneficial for reliable agent 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 coverage is only 25% (only rationale has description). Description does not explain 'from_task_id', 'to_task_id', or the 'relation' enum values. Only adds minor value for 'rationale'. Falls short of compensating for low 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?

Clearly states 'Create a dependency edge between two existing tasks' – a specific verb and resource. Distinguishes from sibling 'unlink_intentions' which removes a dependency.

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 says 'Use to express discovered ordering constraints' with an example. Mentions constraints: 'Both tasks must be in the same plan' and 'Server rejects cycles.' Could clarify when not to use (e.g., if tasks are already linked).

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 burden. It states the tool lists blueprints and mentions filters, implying a read-only operation. It adds context beyond the schema but does not discuss 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 a single, front-loaded sentence that conveys purpose and filter options 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?

While there is no output schema, the description sufficiently covers the tool's functionality for listing blueprints. It lacks details like pagination or sorting, but these are 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?

With 0% schema description coverage, the description compensates fully by naming all three parameters (scope, visibility, owner_only) and explaining their enum values and purpose, directly mapping to the input schema properties.

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

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

The description states the verb 'list', the resource 'blueprints', and specifies the scope (visible to user) and available filters. This clearly distinguishes it from sibling tools like 'list_plans' or 'list_goals'.

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 indicates when to use this tool (to list blueprints visible to the user) and mentions filtering options, but does not explicitly exclude scenarios where other tools might be better suited.

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, so the description carries the full burden. It implies a read-only operation ('list', 'returns'), but does not explicitly state read-only behavior, auth requirements, rate limits, or pagination. It discloses return content but lacks comprehensive behavioral 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?

Two concise sentences that front-load the main action and return value without any extraneous words or repetition. Every word is valuable.

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 no output schema, the description provides the basic purpose and return structure. However, it lacks guidance on using the filter parameter and does not address behavioral aspects like read-only safety. More detail, especially on parameters, would make it complete.

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

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

The description provides no explanation of the 'filter' parameter or its sub-properties, despite zero schema description coverage (0%). The schema has some descriptions on workspace_id, but overall the description fails to add any meaning beyond the schema, leaving the agent to guess parameter usage.

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 goals with health rollup, including aggregate counts and per-goal summary. This uniquely distinguishes it from sibling tools like create_goal, update_goal, and goal_state, 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 on when to use this tool vs. alternatives. The description does not mention when not to use it, prerequisites, or differentiate from other list tools like list_blueprints or list_plans, leaving the agent to infer usage solely from the name.

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?

Without annotations, the description partially explains behavior: it lists plans and returns specific fields. However, it does not disclose whether the operation is read-only, any side effects, pagination, or error handling. The description is adequate but not comprehensive.

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: the first states the primary function, the second explains the output and its purpose. Every sentence is informative and non-redundant.

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 nested parameter object and lack of output schema, the description covers the output fields and basic filtering. However, it omits details on parameters like workspace_id and limit, and does not mention pagination or ordering. It is sufficient but not fully complete.

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

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

The description adds meaning beyond the schema by listing the filter dimensions (status, visibility, text query) and their purpose. Although the schema has a nested object with some descriptions, the top-level 'filter' parameter lacks description, and the description compensates by summarizing the filter options.

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 ('List') and resource ('plans'), and specifies the filtering options and returned fields. It clearly distinguishes the tool from sibling list tools (e.g., list_blueprints, list_goals) by its name and content.

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

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

The description implies the tool is used to select a plan for further operations ('so you can pick a plan to operate on without round-tripping briefing'), but it does not explicitly state when to use this tool versus alternatives like plan_analysis or update_plan. No direct usage guidance is provided.

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

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

Discloses one behavioral trait: returns archived workspaces only when include_archived=true. However, with no annotations, other behaviors (e.g., read-only, authentication, pagination) are not addressed, leaving gaps in 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?

Two sentences, no redundant words. The main action is front-loaded, followed by a concise explanation of workspace and a key behavioral note.

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

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

Covers essential aspects: action, resource, scope, and special case for archived workspaces. However, missing details like pagination or sorting; but for a simple list tool with 2 params and no output schema, it is adequately 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?

Description adds context beyond schema: 'organization' is linked to 'organization_id', and the include_archived parameter is explained with the 'only when' condition. Schema coverage is 50%, but description compensates well for both 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?

Description clearly states the action ('List workspaces'), the resource ('workspaces'), and the scope ('in an organization'). It also defines what a workspace is and specifies the behavior for archived workspaces, making the purpose very clear and distinct from sibling 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 versus alternatives (e.g., list_goals, search). The description does not mention prerequisites or provide contextual usage rules.

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

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

The description discloses that the tool is cycle-safe, meaning the server rejects cycles, and mentions optional position setting. This adds value beyond the absence of annotations, though it does not cover authorization or side effects.

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, front-loaded sentences cover the core purpose, cycle-safety, and optional parameter. 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?

Given no output schema, the description adequately covers key behaviors (reparenting, cycle-safety, position). Missing return value specification, but overall sufficient for a move 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 50% (plan_id and position have descriptions). The description clarifies 'position' as order_index and implies plan_id is auto-resolved, but adds nothing for node_id or new_parent_id beyond obvious naming.

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 'Reparent' and resource 'node within the same plan', clearly distinguishing it from siblings like delete_node, update_node, etc.

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

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

While the description mentions cycle-safety and optional position, it lacks explicit guidance on when to use this tool versus alternatives like update_node or when not to use it. The context is implied but not fully directive.

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. Description says 'reads' implying read-only, but does not disclose error behaviors, auth needs, or what happens for invalid inputs.

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 but packs multiple analysis types. Could be better structured but is not excessively long.

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 4 parameters with enums and no output schema, the description lacks detail on when to use node_id or scenario, and what the tool returns.

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 0%. Description does not explain parameters like plan_id, type, node_id, scenario. No information on dependencies (e.g., node_id needed for impact).

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 performs advanced plan reads, listing specific analysis types: impact, critical path, bottlenecks, coherence. It distinguishes from siblings like list_plans or update_plan.

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 versus alternatives like list_plans or update_plan. No mentioning of prerequisites or 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, description carries full burden. It states it creates tasks and dependency edges, and defaults to 'active' status. But it omits details like error handling, idempotency, or side effects on existing tasks.

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 plus a default status note. Every word is necessary, no redundancy, and key 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?

The description covers the chain's structure, use case, and default status. Without output schema, it could mention return value or confirmation, but it is sufficient for a creation tool with well-described parameters.

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 description does not add significant meaning beyond the existing parameter descriptions. The description's explanation of the chain structure is not parameter-specific, so it adds minimal value over 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 the tool creates a Research->Plan->Implement chain under a parent task/phase, with specific verb and resource. It distinguishes from siblings like 'derive_subgoal' or 'form_intention' which create different structures.

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 recommends use when 'tackling work with significant unknowns', providing clear context. However, it does not mention alternatives or when not to use it, lacking full comparative 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?

With no annotations, the description carries full burden. It discloses that writes go to the real decisions table (not knowledge graph) and that resolution is via resolve_decision. But it omits details on side effects, authorization needs, rate limits, or whether queuing is reversible.

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, no filler, front-loaded with the core purpose. Each sentence adds essential information: purpose, distinction from previous pattern, and resolution pathway.

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?

Considering the tool has 10 parameters and no output schema, the description does not cover return behavior, confirmation, or error conditions. The proposed_subtasks parameter is complex but not explained in the description. However, the description does mention the key resolution mechanism.

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 90%, so the input schema already provides adequate descriptions for most parameters. The tool description adds no additional parameter-level meaning beyond what is in the schema, achieving baseline 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?

Description clearly states the tool queues a decision for human review, distinguishes itself by writing to the real decisions table instead of the knowledge graph, and explicitly replaces the autopilot pattern using add_learning with a specific title prefix. It also mentions resolution via resolve_decision, providing a complete purpose.

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

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

Description provides explicit guidance by contrasting with add_learning pattern and noting resolution via resolve_decision. However, it lacks explicit 'when to use vs. when not to use' statements and does not mention alternatives among sibling tools beyond add_learning.

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, so description carries full burden. It discloses that the tool returns multiple data types in one shape and that result_kind controls payload. However, it doesn't mention side effects, auth needs, rate limits, or behavior with no results. Adequate but not thorough for a complex 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?

Two sentences, front-loaded with purpose, efficient. Every sentence adds value: states what it does, mentions result_kind control, and notes replacement of legacy tools. No 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 7 parameters including nested objects and no output schema, the description is brief. It doesn't explain the output shape ('one shape') or how to interpret combined results. With siblings like search and list_goals, more context on when to use this vs. others would help. Adequate but incomplete for full understanding.

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 29% (low). Description adds value for result_kind ('controls payload size') but does not explain query, scope, since, entry_type, max_results, or include_contradictions beyond schema. With such low coverage, description should compensate more; it falls short.

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 it's a universal knowledge graph query returning facts, entities, episodes, and contradictions. It specifically mentions replacing legacy tools (recall_knowledge legacy, find_entities, get_recent_episodes, check_contradictions), distinguishing it from those. The verb 'query' and resource 'knowledge graph' are specific.

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 says it replaces multiple tools, giving clear context for when to use it over those legacy alternatives. Suggests using result_kind to control payload, but does not provide guidance on when not to use it or alternatives among siblings (e.g., search). Implied usage but no 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?

With no annotations, the description carries full burden. It clearly states the key behavioral trait 'without changing status', which is good. But it lacks details on prerequisites (e.g., task must be claimed), side effects (e.g., message logging), permissions, or reversibility.

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, front-loads the purpose, and contains no redundant or irrelevant 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?

Given no output schema, low parameter count, and adequate annotations from context signals, the description covers the core purpose and usage. However, it could be more complete by mentioning error conditions or what happens if the task is not claimed.

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 67% (2 of 3 params have descriptions). The description adds no additional parameter information beyond what the schema already provides. Per criteria, with coverage > 80% baseline is 3, but here coverage is 67%, still the description does not compensate.

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

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

The description uses a specific verb 'release' on a specific resource 'claimed task', and distinguishes from simply changing status by stating 'without changing status'. It also lists explicit use cases: explicit handoff or abandonment.

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 ('for explicit handoff or abandonment'), giving clear context. However, it does not provide when-not-to-use guidance or name alternative sibling tools, though the purpose implies differentiation.

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

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

With no annotations, the description carries the full burden. It discloses authorization rules and server-side rejection behavior, which are critical behavioral traits beyond basic CRUD.

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 wasted words. The purpose appears in the first sentence, and constraints follow immediately.

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

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

The tool has three parameters and no output schema. The description covers authorization but omits details like irreversibility, return value, or what happens after removal. For a simple removal it's minimally 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 description coverage is 0%, so the description must compensate. It does not explain any of the three parameters ('organization_id', 'membership_id', 'reason'), leaving their semantics unclear. For instance, 'membership_id' is not defined.

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 ('Remove a member') and the resource ('organization'), which is specific and distinguishes it from siblings like 'invite_member' (add) or 'update_member_role' (modify role).

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

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

The description provides explicit caller requirements (owner or admin) and constraints (admins cannot remove other admins, cannot remove owner), giving clear context for when to use. However, it does not explicitly compare to alternative member-management 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?

No annotations are provided, so the description must disclose behavioral traits. It only states the action types and optional fields. Missing details: side effects of resolution, permission requirements, state changes, or what happens to the decision (e.g., removed from pending list). The description is too brief to inform an agent about important behaviors.

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: two sentences that clearly state purpose and usage context. Every sentence is necessary and contributes meaning. No fluff.

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

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

Given the tool has 5 parameters, no output schema, and no annotations, the description is incomplete. It lacks information about the return value, error handling, the role of plan_id (required by API path), and the consequences of resolving a decision. The description covers only the basic action and partial usage context, leaving significant gaps for an AI 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?

Schema coverage is 60%, and the description adds value by listing the action enum values, which are also in the schema. However, it does not explain the decision_id parameter (missing schema description) or add extra context beyond the schema for plan_id, message, or selected_option. It meets the baseline but does not compensate for gaps.

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 (resolve) and the object (pending decision), and provides specific use cases (from Cowork artifact buttons or after human response). It effectively distinguishes from siblings like queue_decision.

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 mentions when to use: from Cowork artifact buttons or after a human responds in chat. It does not mention when not to use or alternatives, but the context is clear and provides good guidance for a specific scenario.

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 bears full burden and clearly discloses the behavioral scope: what is captured and what is excluded. This adds meaningful context beyond the tool's name.

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, front-loaded with the core purpose, and no extraneous 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?

Given no output schema, the description does not explain what the tool returns (e.g., blueprint ID) or mention prerequisites (e.g., plan existence). It covers inputs and exclusions reasonably but lacks output details.

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 only 20% (only title has a description in schema). The tool description does not elaborate on any parameters (plan_id, title, description, visibility, tags), so the agent must rely solely on schema names.

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

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

The description clearly states the tool's purpose: snapshotting a live plan into a new plan-scope blueprint. It specifies what is captured (structure, agent_instructions, dependencies) and what is excluded (run-state), distinguishing it from siblings like fork_blueprint.

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 on live plans and lists captured/excluded elements, but it does not explicitly state when to use this tool versus alternatives (e.g., fork_blueprint) 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?

No annotations are provided, so the description carries the full burden. It fails to disclose behavioral traits such as whether the operation is read-only, performance implications, authorization requirements, or rate limits. The description simply says 'text search' without detailing side effects.

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 exceptionally concise with two short sentences. Every word is purposeful with no redundancy or filler. The key 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?

For a tool with 4 parameters including a nested object and no output schema, the description is too brief. It omits details about scope, scope_id, filters, and return values. The description does not sufficiently inform an agent about how to use the parameters or what to expect from the output.

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 0% schema description coverage, the description should compensate but only provides minimal meaning for the 'query' parameter. It does not explain the 'scope', 'scope_id', or 'filters' parameters, leaving their semantics unclear beyond what the schema structure offers.

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 performs text search across plans, nodes, and content, specifying the verb 'search' and the resource. It also indicates usage for finding entities by title or fragment. However, it does not explicitly differentiate from sibling tools like recall_knowledge, which might also retrieve entities.

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 a usage hint ('Use for finding entities by title or fragment') but lacks explicit guidance on when not to use this tool or alternatives. It does not address scenarios where other tools might be more appropriate.

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 discloses key behaviors: atomicity, authentication requirements, and the limitation that collaborators must be specified by user_id. However, it does not describe failure modes, side effects, or return values, which would be expected for a mutation 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?

The description is two sentences, front-loaded with the core action and constraints. Every sentence adds value, with no redundant or irrelevant 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?

The description covers the main function, constraints, and a limitation, but lacks details on return values, error handling, and what happens if the atomic operation fails. For a tool with 4 parameters and no output schema, more completeness would be beneficial.

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

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

The description adds context beyond the schema by explaining that collaborators are specified by user_id (not email) and emphasizing atomicity. However, schema coverage is only 25%, and the description does not elaborate on role meanings or validation constraints.

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 atomically changes plan visibility and manages collaborators, distinguishing it from other plan tools like delete_plan or update_plan. It uses specific verbs and resources, and highlights the atomicity.

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 specifies prerequisites (caller must be owner or admin) and notes that email-based invites are UI-only, providing guidance on when not to use this tool. However, it does not explicitly mention alternative tools like invite_member or remove_member.

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 discloses the progressive nature of context, depth effects, and the automatic inclusion for RPI tasks. It doesn't mention side effects (likely none) but hints at a token budget parameter, which adds 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 sentences, front-loading the purpose and depth summary, then adding a key specialization. Every sentence provides necessary information 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?

The description covers depth levels and the RPI special case, but lacks explanation of token_budget semantics and return format. Given no output schema, the agent lacks guidance on expected output structure, making it 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 0%, so description must compensate. While it explains depth values, it does not describe 'task_id' or 'token_budget' beyond their schema types. Token_budget's purpose (e.g., limit, hint) is ambiguous, leaving semantic gaps.

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 'Get progressive context for a task' – a specific verb and resource. The depth levels and automatic inclusion for RPI tasks differentiate it from sibling tools, which are mostly CRUD or planning operations.

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 depth levels and a special case for RPI tasks, providing context on when to use different depth values. However, it does not explicitly state when not to use the tool or mention alternatives, though sibling tools do not offer similar functionality.

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 only indicates a destructive action ('Remove') without any annotations. It fails to disclose side effects, reversibility, required permissions, or impact on related data. For a mutation tool, this lack of transparency is a significant 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?

The description is a single, front-loaded sentence with no wasted words. It is concise but could benefit from additional key details without becoming verbose.

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

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

Given the absence of annotations, output schema, and the presence of a missing parameter description, the description is incomplete. It does not specify return values, prerequisites, or behavioral context, leaving significant gaps for an agent selecting this tool.

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

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

Schema descriptions cover 67% of parameters (plan_id and reason), but the description adds no extra meaning beyond the schema. The required parameter 'dependency_id' lacks a schema description and is not elaborated in the tool description, leaving its semantics unclear.

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 ('Remove a dependency edge by id') and the resource ('dependency edge'), which aligns with the tool name 'unlink_intentions'. However, the term 'dependency edge' could be clarified for users unfamiliar with the domain. It is distinct from sibling tools like 'link_intentions' and 'delete_node'.

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 'link_intentions' or 'delete_node'. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the action 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?

With no annotations, the description carries the burden. It discloses atomicity ('All changes apply together') and lists the subsumed side effects. However, it lacks details on idempotency, error handling, or permissions needed. No contradiction with annotations (none 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 concise (two sentences) and front-loaded with 'Atomic goal update'. It efficiently conveys the key point but could benefit from a clearer structure (e.g., listing subsumed operations separately).

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

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

Given the complexity (nested object, multiple subsumed operations) and no output schema, the description provides reasonable completeness about purpose and atomicity. It does not cover return values or error conditions, but for an update tool, it is 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 coverage is 0%, so the description must compensate. It indirectly explains some parameters via subsumed operations (e.g., add_linked_plans, add_achievers), but does not cover all 'changes' properties (e.g., title, priority). The description adds value by grouping related fields but remains incomplete.

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 'Atomic goal update' and lists the subsumed operations (update_goal, link_plan_to_goal, etc.), which distinguishes it from siblings like create_goal, derive_subgoal, and update_node. It uses specific verbs and 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 implies that this tool should be used instead of separate tools for linking plans and managing achievers, providing clear usage context. However, it does not explicitly state when not to use it or mention alternatives beyond the subsumed 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 carries full burden. It discloses key behavioral traits: required permission level and a rejection condition for last admin. This adequately informs the agent of critical constraints, though minor details like idempotency or immediate effect are omitted.

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 consists of two concise sentences with no redundancy. Every sentence adds value: first states purpose, second gives critical constraints.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers core functionality and key restrictions. It does not mention any additional details like reversibility or side effects, but these are not essential 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 only 33% (membership_id has a description). The description adds no further parameter-specific details beyond the schema. It provides overall context about the caller requirement, but does not elaborate on organization_id or new_role 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 explicitly states 'Change a member's role within an organization,' providing a clear verb+resource combination. It further clarifies constraints, distinguishing it from sibling tools like invite_member or remove_member.

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 specifies when to use the tool and includes important prerequisites (caller must be org owner) and conditions (server rejects demoting last admin). While it does not explicitly list when not to use, the context of sibling tools makes it 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?

With no annotations provided, the description carries full burden. It discloses atomic edits, lists editable properties, and notes rejection of node_type changes when children exist. This is good but could mention permissions or side effects.

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 with front-loaded purpose. Every sentence adds value: listing editable properties, distinguishing from update_task, noting a behavioral constraint. 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 tool has 8 parameters with enums and nested objects. The description covers main editable properties and a key constraint, but lacks details on return values, plan_id auto-resolution, and metadata structure. Given complexity, it could be more 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 very low (13%). The description adds meaning by listing the editable properties and noting a constraint on node_type, partially compensating. However, it does not detail format or constraints for each parameter beyond the schema enums.

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

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

The description explicitly states the tool edits node properties atomically, lists the specific properties, and distinguishes from update_task for status transitions. This is a specific verb+resource+scope that clearly differentiates from sibling 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?

The description provides explicit guidance on when to use this tool (for editing properties) and when not (status transitions belong on update_task). It names the alternative tool. However, it does not cover all potential sibling tools like delete_node or move_node.

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 full burden. It discloses atomic updates, soft-delete behavior, recovery option, and that hard delete is separate. However, it omits auth requirements (except for hard delete), rate limits, or other side effects. Adequate but not thorough.

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 that front-load the main purpose and then provide specific behavioral notes. No redundant or extra information. Every sentence adds value.

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

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

Given no output schema, the description does not explain return values. It covers key behaviors but does not elaborate on parameters like 'GitHub linkage' or 'metadata' merging behavior. With 7 parameters and low schema coverage, slightly more detail 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 description coverage is low (29% only for 'metadata' and 'restore'). The description adds meaning by explaining that 'status'='archived' triggers soft-delete and that 'restore' is required for un-archiving. It also implies atomicity across all properties. This compensates for the schema gaps.

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 'Edit any plan property atomically' and lists specific properties. It distinguishes this tool from 'delete_plan' by noting soft-delete via status='archived' versus hard delete via REST-only endpoint, providing clear differentiation.

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 explicit guidance on when to use this tool (editing plan properties) and when not (hard delete requires REST-only admin auth). It also explains the restore flag for un-archiving. However, it does not compare with sibling tools that update other resources, which is acceptable given they target different entities.

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 full burden. It discloses key behaviors: atomic operation, idempotence, and the optional actions. This is sufficient to understand the tool's nature, though additional details about potential side effects (e.g., knowledge episode writing) are left to the 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 extremely concise with two sentences containing no filler. Every phrase adds value, clearly stating purpose, optional actions, idempotency, and replacement of sibling tools.

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 9 parameters and no output schema, the description provides sufficient high-level context for an agent to understand the tool's role. It explains the atomic transition and replacement of fan-out tools. Minor gap: does not explain default log_type behavior or valid status transitions, but these are covered by schema enums.

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 high (78%) and most parameters have descriptions. The description does not add detail beyond the schema, providing only high-level context. Since baseline is 3 for high coverage, this score 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?

Description specifies 'Atomic task state transition' with clear verb and resource. It details that it updates status, optionally appends log entry, and optionally releases claim. It also distinguishes itself by stating it replaces three previous tools (quick_status, add_log, release_task), which helps with identification.

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

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

The description explicitly says 'Replaces quick_status + add_log + release_task fan-out,' indicating when to use this tool instead of multiple others. However, it does not provide explicit when-not-to-use guidance or mention alternatives like the sibling 'release_task' for cases where only claim release is needed.

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