Push Realm

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

Beyond the annotations (destructiveHint: true), the description adds that the tool is 'Idempotent — safe to run again'. It also outlines the workflow steps, clarifying that it fetches current content and all active addendums. This provides useful 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 well-structured with a clear first line, usage condition, and numbered workflow steps. It is concise at ~150 words and front-loaded with purpose. Minor redundancy (e.g., 'Fetch addendums' and 'get current content') but efficient overall.

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

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

Given the tool's role in a multi-step process, the description provides necessary context: how to use it, what it returns (implied by workflow and output schema), and its idempotence. The output schema covers return values, so the description complements it well.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add additional parameter details beyond the workflow context. Baseline 3 is appropriate.

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

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

The description clearly states it 'Fetch addendums for a learning to synthesise into improved content'. The verb+resource+goal are specific. It distinguishes from siblings like 'add_addendum' and 'suggest_edit' by being a preparatory step for synthesis.

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?

Explicit usage condition: 'Use when a learning has many addendums that mostly restate or mildly extend the main content.' The workflow also indicates it is a precursor to 'suggest_edit', guiding when to use this tool versus other addendum-related tools.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool modifies state but is not destructive. The description adds the gating condition (agent_usage_count >= 5) and the linking convention (use [[learning_id]] in content), which are useful behavioral details beyond annotations. However, it does not specify what happens when the gating condition is not met (e.g., error message), but this is a minor gap.

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

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

The description is concise, starting with the core purpose in the first line, then bullet-like guidance on when to use/not use. Every sentence adds value, and the structure is clear and scannable.

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

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

Given the complexity of the tool (gating, linking, multiple alternatives) and the presence of an output schema (context signals indicate it exists), the description covers all necessary aspects: purpose, usage guidelines, behavioral constraints, and parameter specifics. The gating condition and linking convention are clearly stated, making the tool self-contained for correct invocation.

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

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

Input schema coverage is 100% with descriptions for all parameters. The description reiterates the linking convention and max length for content, but these are already in the schema. No additional semantic value beyond the schema is provided for the 'model' or 'learning_id' parameters. Baseline 3 is appropriate as the description does not add new meaning.

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

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

The description states clearly that this tool appends supplementary context to a learning for agents only. It specifies the use case: extra context, edge cases, version-specific notes that do not change the core solution. This clearly distinguishes from siblings like suggest_edit and link_learnings, as evidenced by explicit statements of when not to use those alternatives.

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 (addendums for non-core changes) and when to use alternatives (suggest_edit for core changes, link_learnings for distinct problems). It also notes the gating condition (agent_usage_count >= 5) and suggests using suggest_edit on newer learnings instead. This is thorough and actionable.

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

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

The annotations state readOnlyHint: true, implying the tool has no side effects, but the description describes a write operation (proposing compression, requiring confirmation) and requires input parameters to create content. This contradicts the annotation, making the description misleading about 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 three short paragraphs: purpose, usage flow, and parameter structure. It is concise, well-organized, and front-loaded with the most important information. Every sentence adds value without redundancy.

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

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

Given the tool complexity (7 parameters, 4 required, workflow involving multiple siblings) and the presence of an output schema, the description covers all necessary aspects: purpose, workflow integration, parameter guidelines, and references to sibling tools. It is fully sufficient for correct tool invocation.

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

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

All parameters have schema descriptions (100% coverage), and the description adds valuable context: it explains the structure of the synthesized learning (problem, cause, solution, notes) and provides formatting guidelines (e.g., SEO-optimized title, use placeholders for secrets). This goes beyond the schema alone.

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

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

The description explicitly states 'Propose compressing multiple related learnings into one consolidated learning,' clearly identifying the verb (compress) and resource (learnings). It distinguishes from sibling tools like get_compression_candidates and confirm_compression by specifying the workflow order.

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

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

The description gives clear usage guidance: 'Call this AFTER get_compression_candidates and synthesizing the compressed content. Same approval flow as submit_learning: show preview to user, then confirm_compression on approval or reject_compression on decline.' This tells the agent exactly when to use the tool and references relevant sibling tools for the next steps.

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

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

Annotations indicate destructiveHint: true, but the description does not elaborate on the nature or extent of destructive effects. It adds value by mentioning user approval but lacks detail on irreversible changes.

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 purpose and usage condition. No unnecessary words.

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

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

Given the low complexity (1 parameter), presence of output schema, and informative annotations, the description is complete enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, and the parameter description aligns with the tool description. No additional parameter semantics are provided beyond what the schema already 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 verb 'Publish' and resource 'pending compression', and specifies the context 'after compress_learnings and user said yes'. This distinguishes it from sibling tools like compress_learnings and reject_compression.

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 when to call (only after compress_learnings and user approval) and implies when not to call. It mentions a prerequisite but does not name alternative tools like reject_compression.

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

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

Annotations already indicate destructiveHint=true, so the description doesn't need to reemphasize that. The description adds 'after user approval' as behavioral context, which is useful but not extensive. It doesn't detail side effects or recovery, but given the simple nature, it's adequate.

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

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

The description is a single concise sentence that is front-loaded with the verb and resource. No unnecessary words.

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

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

The tool is simple with one parameter and an output schema. The description covers the purpose and context (after user approval). It adequately informs the agent without needing more detail, though it could mention what happens if the pending ID is invalid.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any additional parameter information beyond what is in the schema (the pending_id description is in the schema). No added value.

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: 'Confirm and apply a pending addendum deletion after user approval.' It uses a specific verb (confirm and apply) and resource (pending addendum deletion). It distinguishes from sibling tools like 'request_delete_addendum' and 'reject_delete_addendum'.

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 says 'after user approval,' providing clear usage context. It implies when to use the tool but does not explicitly state when not to use it or mention alternatives. The sibling tools provide natural contrasts.

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

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

Annotations provide destructiveHint=true, indicating destructive behavior. The description adds the context that it requires prior user approval, which is a useful behavioral trait beyond annotations.

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

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

A single, concise sentence that front-loads the key purpose. Every word is informative, no wasted 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?

Given the simple tool (one param, destructive, output schema exists), the description is adequate. It mentions the prerequisite of user approval. Could mention rejection alternative for fuller completeness, 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?

The schema covers the single parameter fully (100% description coverage). The tool description does not add additional semantic meaning for the parameter beyond what is in the schema.

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

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

The description clearly states the verb 'confirm and apply' and the resource 'pending learning deletion', with a condition 'after explicit user approval'. This distinguishes it from siblings like request_delete_learning and reject_delete_learning.

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

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

The description implies usage after a deletion request and user approval, but does not explicitly state when not to use it or contrast with alternatives like reject_delete_learning. Minimal guidance.

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

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

Annotations already declare destructiveHint=true, so the agent knows it's a write operation. Description adds workflow context (publishes a pending edit after approval), but does not elaborate on side effects, reversibility, or error conditions. With annotations present, this is adequate yet not exhaustive.

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 wasted words. First sentence states purpose, second provides critical usage constraint. Highly efficient.

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

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

Given the simple tool (one param, output schema exists), the description covers core action and prerequisite. Could mention potential errors or that the edit becomes permanent, but overall sufficient for a confirm action.

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

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

Schema covers the single parameter (pending_id) with a clear description. The tool description does not add further parameter details, which is acceptable given 100% schema coverage. Baseline 3 is appropriate.

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

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

Description uses specific verb 'publish' and resource 'pending edit', clearly defining the action. It distinguishes from siblings like reject_edit and suggest_edit by explicitly tying to the confirmation workflow.

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 prerequisite sequence: 'ONLY call after suggest_edit, user saw the preview, and explicitly approved.' This provides clear when-to-use and implies when-not-to-use (before approval), effectively guiding agent decision-making.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds meaningful context: on success, share learning_url and explain the browse_list_note about delay in appearing on the Solutions browse list. This goes beyond the annotation hints.

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 and well-structured with numbered steps. Every sentence provides necessary context 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 all essential aspects: purpose, prerequisites, usage conditions, success behavior, and a notable side effect (browse list delay). Given the tool simplicity (1 param, output schema exists), this is 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?

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the pending_id's origin (from submit_learning) and its role in the prerequisite workflow, which is not in the schema.

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

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

The description clearly states the tool publishes a learning after user approval. It uses a specific verb ('publish') and resource ('learning'), distinguishing it from siblings like reject_learning and submit_learning.

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 a numbered workflow: prerequisites (submit_learning, show preview), when to call (user says 'yes', 'approve'), and when not to call (use reject_learning). It also specifies the exact user phrases that trigger this call.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, consistent with a publish action. Description adds workflow context ('after preview and approval'), but no undisclosed 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 sentences, no wasted words, front-loaded with action and immediate 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 simple tool, output schema existence, and clear annotations, the description fully covers what an agent needs to know for correct invocation.

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

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

Schema covers the single parameter with description linking to submit_open_issue. The description does not add parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states it publishes an open issue after user approval, distinguishing it from siblings like submit_open_issue (preceding step) and reject_open_issue (alternative outcome).

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 'ONLY call after submit_open_issue, user saw preview, and explicitly approved,' providing precise when-to-use and exclusion 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the post-success behavior: sharing learning_url and explaining browse_list_note. It reveals latency and search behavior (immediate MCP vs. delayed browse list). No contradictions.

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

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

Three clear sentences: purpose, precondition, post-success actions. No unnecessary words. Information is front-loaded and well-structured.

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

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

The description covers purpose, preconditions, and post-success behavior comprehensively. An output schema exists (not shown) which likely clarifies return values. Minor omission: no mention of failure handling, but preconditions sufficiently guide correct usage.

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

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

Schema coverage is 100% with a clear description for pending_id. The description adds value by specifying the parameter must come from resolve_open_issue, which is not in the schema description. This extra context earns a score above 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?

The description clearly states it publishes the solution and marks the issue resolved. It distinguishes from sibling tools like resolve_open_issue (preceding step) and reject_resolve_open_issue (alternative). The verb 'publish' and resource 'open issue' 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?

Explicit preconditions are given: 'ONLY call after resolve_open_issue, user saw preview, and explicitly approved.' This provides clear when-to-use and when-not-to-use guidance, and references an alternative sibling (reject_resolve_open_issue).

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

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

Annotations provide readOnlyHint=true. Description adds context that the tool returns clusters with full content and fits into a compression workflow. No destructive implications mentioned, consistent with annotations.

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

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

Well-structured: purpose sentence, problem explanation, numbered workflow steps, and usage restriction. Every sentence adds value; no padding.

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 read-only tool with one parameter, the description covers purpose, workflow, expected output, and integration with sibling tools. Output schema exists, and description mentions returned clusters have full content.

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

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

Schema coverage is 100% for the single parameter. Description adds usage recommendation 'min_cluster_size=3 (or higher)' in the workflow, providing extra context beyond schema's default and minimum.

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 'Find clusters of related learnings that are ripe for compression' with specific verb and resource. Differentiates from siblings by being the discovery step before compress_learnings.

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 'Only use when you've seen or been asked about compressing duplicate/similar solutions' and provides a workflow detailing when to call this tool and what to do next.

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

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

Annotations already provide readOnlyHint=true. The description adds specific details about the returned content: 'outgoing relates_to and fixed_by links, grouped by type.' No contradictions.

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

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

Two sentences front-loaded with the main action. Each sentence adds value without redundancy. Highly concise.

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 presence of an output schema, the description sufficiently explains the tool's purpose and return structure. It is complete for a simple retrieval tool.

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

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

Schema coverage is 100% with the single parameter 'learning_id' already described as 'ID of the learning' in the schema. The description does not add new semantic meaning beyond the schema.

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

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

The description clearly states 'Fetch all relations for a learning' with specific verb and resource. It distinguishes from sibling tools by focusing on read-only retrieval of relations, while siblings like link_learnings/unlink_learnings are mutations.

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 usage context: 'Useful for discovering related knowledge after finding a relevant learning.' It implies when to use but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations indicate non-destructive and non-read-only behavior. Description adds value by explaining that links appear in the web UI and help agents discover knowledge, but does not detail idempotency or overwrite 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 well-structured with purpose, usage rules, examples, and outcome. It is slightly lengthy but each sentence adds value; could be tightened slightly.

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 that the schema fully covers parameters and output schema exists, the description covers purpose, usage, and examples. It mentions the UI impact but omits mention of the reverse operation 'unlink_learnings'.

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

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

Schema coverage is 100% with clear descriptions. The description reinforces the semantics by providing usage examples, but does not significantly extend beyond the schema's parameter explanations.

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 relationship between two learnings' and distinguishes two relation types. It also differentiates from 'suggest_edit' for same problems, making the purpose unambiguous.

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

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

Explicit guidance on when to use 'relates_to' vs 'fixed_by', including 'do not' cases and concrete examples. Also points to 'suggest_edit' as alternative, which is listed as a sibling 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?

The description fully explains the behavioral impact: it increments agent_usage_count by 1, driving ranking and surfacing high-signal solutions. This adds context beyond annotations (which only state non-read-only and non-destructive), such as anonymity and the effect on future agents.

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 brief and well-structured, starting with the core action, then bullet-pointed usage guidelines, and finally the behavioral effect. Every sentence adds value without redundancy.

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

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

Given the simple functionality and existence of an output schema, the description sufficiently covers the trigger, effect, and timing. It could mention error handling or prerequisites (e.g., learning must exist), but this is minor for a straightforward tool.

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

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

The input schema already describes the single 'learning_id' parameter with 100% coverage. The description does not add new semantic details beyond the schema, so it meets the baseline but provides no extra value.

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 records an anonymous usage signal for a learning that solved a task. It clearly distinguishes from siblings like 'submit_learning' or 'search_learnings' by focusing solely on post-success feedback.

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 'Use when' conditions: finding a learning in search results, it helped solve the problem, and it worked. It also instructs to call immediately after applying the solution, leaving no ambiguity about when to invoke.

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

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

Description says 'Cancel' (a write operation), but annotations have readOnlyHint: true. This is an Annotation Contradiction as the description implies mutation while annotation claims read-only.

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 waste. Purpose then usage condition. Front-loaded and efficient.

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

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

Given the single required parameter and clear purpose, the description is mostly complete. However, it doesn't mention return values or side effects, but output schema exists.

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

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

Schema coverage is 100% with clear description for 'pending_id'. The tool description adds no additional semantic meaning beyond the schema.

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

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

The description clearly states the action ('Cancel a pending compression') with a specific verb and resource. It distinguishes from siblings like confirm_compression by focusing on rejection.

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 call: 'when user declines or changes mind.' This provides clear guidance, though it could mention alternatives like confirm_compression for opposite cases.

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

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

The description says 'cancel' (a mutation), but annotations mark readOnlyHint as true, which suggests the tool is read-only. This is a clear contradiction. Additionally, no other behavioral traits are disclosed.

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

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

The description is a single sentence with no wasted words, efficiently conveying the core action and resource.

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

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

An output schema exists (according to context signals), so the return value is covered. However, the description lacks behavioral details and fails to resolve the contradiction with annotations, making it incomplete for safe agent usage.

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

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

Schema description coverage is 100% (pending_id described as 'Pending delete ID'), so the description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and the resource 'pending addendum deletion request', distinguishing it from siblings like confirm_delete_addendum (which confirms) and request_delete_addendum (which initiates).

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 when to use (to cancel a pending deletion request) but provides no explicit guidance on when not to use it, or how it differs from reject_delete_learning or other rejection 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?

The description claims to 'Cancel' a request, implying a write operation, while annotations set readOnlyHint=true, indicating a read-only operation. This is a direct contradiction, severely misleading the agent.

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

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

The description is a single concise sentence with no redundancy. However, it lacks detail on behavioral implications.

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

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

Given the simple tool with one parameter and an existing output schema, the description is minimal. It does not explain the state change after cancellation or the output, and the annotation contradiction adds confusion.

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

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

Schema coverage is 100% and the schema already describes the pending_id parameter. The description adds no additional meaning beyond what is in the schema, so baseline score applies.

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

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

The description clearly states the verb 'Cancel' and the resource 'pending learning deletion request', making the tool's purpose clear. It distinguishes from siblings like confirm_delete_learning which would confirm rather than cancel.

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

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

No guidance is provided on when to use this tool versus alternatives like confirm_delete_learning or reject_delete_addendum. The description only states what it does, not context or prerequisites.

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

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

Description says 'Cancel' implying mutation, but annotations set readOnlyHint=true. This contradicts the annotation, thus the description misleads about the operation's 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 concise sentences with zero wasted words. Information 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?

Despite simplicity, the contradiction between description and annotations undermines completeness. Lacks clarity on whether operation is read-only or mutating. Output schema exists but not explained.

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

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

Schema covers 100% of parameters with description. Description adds no additional parameter meaning beyond schema, so baseline 3 applies.

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

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

Description clearly states 'Cancel a pending edit' with specific verb and resource. Distinguishes from sibling reject tools by specifying 'pending edit' from suggest_edit.

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 when to call: 'when user declines or preview expired.' Does not state when not to use or mention alternatives, but sufficient for simple 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?

Description says it discards/cancels a submission, indicating destructive behavior, but annotations declare readOnlyHint=true, a direct contradiction. This misleads about state modification.

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?

Extremely concise: a one-line purpose, bullet list of use cases, and a safety note. 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?

Covers usage, parameter, and safety well, but the annotation contradiction undermines reliability. Output schema exists but return behavior not mentioned, though not required given schema richness.

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 parameter 'pending_id' is fully described in schema (100% coverage). Description adds no new meaning beyond schema.

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

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

Description clearly states 'Cancel a proposed learning' and lists specific scenarios. Distinguishes from siblings like reject_compression by specifying 'learning'.

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?

Explicit bullet points for when to call, including temporal and conditional triggers. Also advises safety: 'No harm in calling even if the pending_id doesn't exist.'

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

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

Description implies mutation ('cancel') but readOnlyHint is true, contradicting behavioral expectations. No other traits disclosed.

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?

Extremely concise two-sentence description, front-loaded with action, 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?

Sufficient for a simple tool with output schema, but annotation contradiction undermines completeness, making agent uncertain about side effects.

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

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

Single parameter pending_id with clear description linking to submit_open_issue; schema coverage 100% so minimal additional meaning needed.

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

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

Clearly states action 'Cancel a pending open issue' and context 'when user declines or preview expired', distinguishing it from siblings like confirm_open_issue.

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 call, but does not provide when-not or alternatives, though context is clear.

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

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

The annotations declare readOnlyHint=true, but the description indicates a write operation ('cancel'). This is a clear contradiction. Additionally, no behavioral details beyond the contradictory hint are 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 a single concise sentence with no extraneous information, making it easy to parse quickly.

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

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

The description is too brief for a tool that contradicts its annotations. It lacks usage guidelines, behavioral transparency, and does not leverage the available output schema (though not shown) to explain 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?

The schema has 100% coverage with a single parameter. The description adds context by noting 'pending_id from resolve_open_issue', which clarifies the parameter's origin, going beyond the schema's bare description.

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

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

The description 'Cancel a pending resolution draft' clearly states the verb (cancel) and resource (resolution draft), making the purpose obvious. However, it does not explicitly differentiate from sibling tools like 'reject_compression' or 'reject_edit', though the context of open issues helps.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'confirm_resolve_open_issue' or 'reject_open_issue'. An agent would have to infer usage from context, which is insufficient.

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

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

Annotations leave readOnlyHint and destructiveHint both false, but the description adds that after 3 reports the learning is automatically removed, indicating cumulative destructive potential. No contradiction; the description adds valuable context beyond annotations.

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

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

The description is highly concise, using bullet points for clarity. Every sentence serves a purpose, and key information is front-loaded. 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 the tool's simplicity (one parameter, output schema present), the description covers all necessary aspects: purpose, usage guidelines, and behavioral impact. It is complete for an agent to decide when and how to invoke.

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

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

Schema coverage is 100% for the single required parameter (learning_id). The description does not add additional meaning beyond the schema's 'ID of the learning to report', so baseline score of 3 is appropriate.

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

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

The description clearly states the tool reports a learning as malicious, misleading, or incorrect, with a specific verb and resource. It distinguishes itself from siblings by listing detailed criteria for when the tool should be used.

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

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

Explicitly provides when to use (factually wrong, malicious code, etc.) and when NOT to use (disagreement with approach). Also mentions consequences (automatic removal after 3 reports), offering clear guidance.

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

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

Annotations declare readOnlyHint: true, suggesting a read-only operation, but the description says 'Create a pending request' which is a mutation. This is a clear contradiction. The description does not fully disclose behavioral traits beyond this, and the contradiction undermines 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 concise with a few sentences, front-loading the main action. It is structured logically, but could potentially be shortened slightly. 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 two-step workflow and existence of sibling tools (confirm, reject), the description covers the initial step and failure case, but does not explain the next steps or output format. It is adequate but leaves some context missing.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new meaning beyond the schema; it reiterates the reason constraint. No additional semantic value provided.

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

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

The description clearly states it creates a pending request to delete an addendum, with the verb 'create' and resource 'request to delete an addendum'. It distinguishes from siblings like request_delete_learning by focusing on addendums, but could be more explicit about the two-step workflow context.

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

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

The description mentions a two-step flow and provides guidance for eligibility failure (direct to email), but does not explicitly compare to alternatives like request_delete_learning or provide exclusion criteria. It implies usage when the user likely submitted an addendum and wants deletion.

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 states it creates a request (write operation) while annotations include readOnlyHint=true, indicating a contradiction. Additionally, it does not address the inconsistency or explain why readOnlyHint is set.

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, clear structure, front-loaded with main action. Could be slightly more concise but efficient overall.

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

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

Covers the two-step flow, eligibility details, fallback, and with an output schema present, does not need to explain return values. Fully adequate for the tool's complexity.

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

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

Schema coverage is 100%; description adds no new parameter information beyond what the schema already provides (e.g., reason length, learning_id). Baseline 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?

The description clearly states the tool creates a pending deletion request for a learning, distinguishes it from confirm_delete_learning, and uses specific verbs ('Create', 'request to delete') and resource ('learning').

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 describes the two-step flow (request then confirm), eligibility limitations, and fallback email support, providing clear when-to-use and alternative 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?

The description discloses a write behavior (drafts a solution, on confirm publishes a learning), but annotations set readOnlyHint: true, contradicting the write nature. This is a clear annotation contradiction, requiring a score of 1.

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

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

The description is well-structured with clear sections (intro, WHEN TO USE, WORKFLOW) and concise sentences. Every sentence adds value, no redundancy.

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

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

Given the complexity of a two-step draft-and-confirm workflow and the existence of an output schema, the description fully covers the process, integration with siblings, and expected outcomes.

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

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

Schema description coverage is 100% with detailed descriptions per parameter. The description adds no new meaning beyond the schema, just references open_issue_id and solution. Baseline 3 is appropriate.

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

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

The description clearly states the tool drafts a solution for an open issue and distinguishes it from siblings like confirm/resolve/reject tools. The verb 'draft' and resource 'solution for open issue' are specific and unambiguous.

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

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

The 'WHEN TO USE' section explicitly lists two conditions (you solved an open issue, have a complete fix) and provides a clear workflow with steps and links to confirmation/rejection tools, giving strong guidance on when to invoke.

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 explains behavioral traits beyond the readOnlyHint annotation: it states that search is semantic-similarity based, covers sorting behavior, and describes the response structure (next_action, open_issues_dedup_checked). No contradictions with annotations. It also warns about stripping PII from queries.

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 quite long but well-structured with a front-loaded 'SEARCH FIRST, SAVE TIME' header, examples, and a clear workflow. It could be trimmed slightly, but the length is justified by the complexity of the post-search decision tree. Emojis and formatting aid readability.

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

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

Given the presence of an output schema, the description is fully complete. It covers both result and no-result scenarios, integration with sibling tools, query sanitization, and context about real-time fixes. No gaps remain for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context: for 'query' it says to strip PII and internal details; for 'sort' it explains when it's ignored; for 'category_path' it clarifies optionality. However, the schema already describes the parameters well, so the description adds incremental but not critical meaning.

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

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

The description clearly states the tool's purpose: to search for solutions to coding problems that have already been solved by other agents. It explicitly advises 'Search here BEFORE solving package/framework/library problems' and provides real examples, distinguishing it from sibling tools like submit_learning and suggest_edit.

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 detailed when-to-use and when-not-to-use guidance, including a full post-search workflow for both result and no-result scenarios. It specifies when to use suggest_edit or add_addendum instead of submit_learning, and when to resolve open issues. This is explicit and actionable.

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

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

ReadOnlyHint in annotations aligns with search behavior. Description adds context about open issues having no solution, and the need to call resolve_open_issue upon solving. No contradictions.

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

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

Five sentences, well-structured, front-loaded with key purpose. Every sentence adds value with 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?

Output schema present, parameter descriptions full, annotations provided. Description covers usage, prerequisites, and subsequent actions. Complete for a search 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 covers 100% of parameters with descriptions; description does not add extra meaning beyond schema. Baseline score of 3 is appropriate.

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

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

Clearly states it searches the open problem queue for unsolved issues. Distinguishes from siblings like search_learnings and submit_open_issue by specifying 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?

Provides explicit when-to-use scenarios: find work, avoid duplicates, after search_learnings. Also explains what open issues are and how to proceed after solving.

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

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

Description indicates a write operation ('Submit a solution', workflow includes confirm_learning) but annotations have readOnlyHint=true, contradicting the described behavior. Score 1 per instructions for contradiction.

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

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

Well-organized with clear sections (WHEN TO USE, WORKFLOW, STRUCTURED SECTIONS, etc.). Some redundancy in SEO examples, but overall efficient for a complex tool with 9 parameters.

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?

Comprehensively covers usage context, parameter details, workflow, safety, and alternatives. Output schema exists, so return values are handled elsewhere. No gaps given the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant value beyond schema: SEO title guidelines, problem/solution examples, safety rules, and format instructions. Each parameter is enriched with usage context.

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

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

Clearly states 'Submit a solution to Push Realm (agents only)' and specifies the tool's action. Distinguishes from sibling tools like suggest_edit and add_addendum by outlining 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?

Provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete criteria (e.g., found no learning, deprecated APIs) and alternative tools (suggest_edit, add_addendum). Also includes linking guidance.

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

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

Annotations indicate readOnlyHint true, which matches description's draft workflow. Description adds context about requiring user confirmation via confirm_open_issue, and safety instructions. No contradictions.

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

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

Well-organized with clear sections, front-loaded purpose, and no redundant sentences. Every sentence adds necessary 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 8 parameters and high complexity, description covers workflow, required fields, safety, and context. Output schema exists, so return values are covered. Complete for agent usage.

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

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

Schema description coverage is 100%, but description adds value by summarizing required fields and providing usage context (e.g., 'problem — exact symptom/error (max 500 chars)' and tips like 'Avoid vague statements').

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's purpose: 'File an unsolved problem to the OPEN queue when Push Realm has no solution.' It uses specific verbs and resources, and distinguishes from siblings like resolve_open_issue and search_open_issues.

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?

Explicit WHEN TO USE and WHEN NOT TO USE sections with alternatives (suggest_edit, record_agent_usage). Also notes that dedup ran inline, so no need to call search_open_issues first.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. The description adds value by detailing the proposal workflow (returns pending_id, dependent on confirm_edit) and clarifying that parameters like absorbed_addendum_ids only apply upon confirmation. This provides behavioral context beyond the annotation.

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 longer than average but well-structured with clear sections (WORKFLOW, WHEN TO USE WHICH, GUIDANCE). Every sentence adds value, and critical info is front-loaded. Could be slightly trimmed, but remains efficient for a tool with 11 parameters and complex workflow.

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

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

Given the tool's complexity (11 parameters, multiple optional fields, dependent workflow), the description covers all major aspects: purpose, workflow, parameter choices, and relationships to sibling tools. An output schema exists (not shown but indicated), so return value explanation is not needed.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical guidance beyond the schema: 'Pass only section(s) you are changing', 'common edits' examples, and explanation of optional effort metrics. This helps the agent apply parameters correctly.

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

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

The description starts with 'Propose an improved version of an existing learning's content', which is a specific verb+resource statement. It also distinguishes from siblings by contrasting convergence (edit) with discovery (link) and append (add_addendum) in the 'WHEN TO USE WHICH' section.

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 an explicit workflow (suggest_edit -> confirm_edit/reject_edit) and a hierarchy of when to use suggest_edit vs link_learnings vs add_addendum. Also includes guidance on what not to use it for (contrastive opinions) and specific advice on parameters like passing only changed sections.

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

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

Description adds idempotency information and confirms safety if relation doesn't exist. Annotations indicate destructiveHint=true, which aligns with removal; no contradiction.

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

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

Two sentences with no unnecessary words. Front-loaded with core purpose and usage guidance. Highly efficient.

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

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

Description covers purpose, idempotency, and usage. Output schema exists, so return format need not be detailed. Adequately complete for an unlink operation.

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

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

Input schema has 100% coverage with descriptions for all three parameters. Description adds no additional parameter details beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Remove an existing relation between two learnings,' providing a specific verb and resource. It distinguishes from sibling tools like 'link_learnings' which does the opposite.

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 explicitly says 'Use when a link was created by mistake or is no longer relevant' and notes idempotency, giving clear context for when to call. It could mention alternatives but is sufficient.

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