Push Realm

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

The description goes well beyond the annotations (readOnlyHint: false, destructiveHint: false) by explaining the conditional behavior: published addendum when agent_usage_count >= 1, or auto-applied notes edit when usage is 0. It also discloses the safety expectation for content.

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

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

The description is compact and well-structured with labeled sections (Use when, Returns, Do not use when, Safety). Every sentence contributes meaningful guidance with no redundancy or filler.

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

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

Given no output schema, the description adequately explains the return behavior ('Returns: the published addendum') and the alternative outcome for unused solutions. It covers when to use, when not to use, and safety, making the tool self-sufficient 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 coverage is 100%, so the baseline of 3 applies. The description adds general context about content (redaction) and the conditional return behavior, but does not enrich parameter-level meaning beyond what the schema already provides.

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

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

The description immediately states the tool's purpose: 'adding a small edge case, version note, or extra context that does not change the core fix.' It clearly distinguishes from sibling tools by specifying when not to use it and naming suggest_edit and submit_solution as 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?

Explicit 'Use when' and 'Do not use when' sections provide clear usage criteria and name concrete alternatives. It also includes a safety instruction about redacting PII, secrets, and proprietary context, giving complete actionable 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 the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavioral details: there is no preview gate, the issue remains open until confirm or usage threshold, and it warns about removing secrets/PII/proprietary context. This adds substantial value over the annotations alone.

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

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

The description is three sentences long, each covering a distinct and necessary aspect: when to use, return behavior, when not to use, and safety. It is front-loaded with the most critical decision-making information and contains zero 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?

Despite having no output schema, the description explains the return behavior (published solution linked as candidate) and the issue lifecycle. It covers usage boundaries, alternatives, and security caveats, making the tool self-sufficient for an agent to invoke correctly without external context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific explanations beyond what the schema already provides; it only touches on the 'solution' content via the safety note. The schema already handles parameter semantics fully.

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

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

The description opens with a specific verb+resource+scope ('publish a candidate fix for an open issue without closing it'), making the tool's function unambiguous. It explicitly contrasts with sibling tools like resolve_open_issue and submit_solution, clearly distinguishing this tool from 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 'Use when' and 'Do not use when' conditions, naming alternative tools for each exclusion case. This gives the agent clear decision rules for when to select this tool versus others.

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 this is a non-destructive write operation. The description adds behavior context by specifying the trigger (applied search result) and the return value (updated usage count). While it doesn't detail side effects like idempotency, the annotation coverage lowers the burden, and the return value provides meaningful transparency.

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

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

The description is extremely concise, using labeled sections for use, return, and non-use. Every sentence serves a distinct purpose, and the structure front-loads the key information, making it easy for an agent to parse and act on.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: when to use, when not to use, and what to expect in return. It is self-contained and sufficient for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100% with a clear description for solution_id. The description adds minor contextual meaning by connecting the ID to a search result, but it doesn't provide additional format or constraints beyond the schema. Thus, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: record usage when a search result has solved the problem. It explicitly mentions the resource (solution) and the action (recording usage), and distinguishes it from siblings by specifying the context of 'applied a search result'. The title 'Record Agent Usage' reinforces the 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?

The description provides explicit 'Use when' and 'Do not use when' conditions, which directly guide the agent on when to invoke this tool versus alternatives. It excludes cases where the fix hasn't been tried or new content is being posted, clearly delineating appropriate usage.

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 reporting increments a count and that removal occurs after 3 reports, along with the return value 'report count.' This goes beyond the annotations, which only indicate read/write/destructive hints. It does not mention other potential side effects, but the provided context is sufficient for a simple reporting action.

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

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

The description is three concise sentences, each serving a clear purpose: usage criteria, output/behavior, and exclusions. It is front-loaded with the most important information and contains no filler or redundancy.

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

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

For a tool with a single parameter, no output schema, and present annotations, the description covers purpose, usage boundaries, output, and the threshold effect. It clearly states what the agent will receive ('report count') and the consequence of repeated reporting. It is complete enough for an agent to use appropriately.

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

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

The single parameter solution_id is already fully described in the schema (100% coverage). The tool description does not add additional parameter-specific semantics beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description explicitly states the tool's purpose: reporting a solution when it is factually wrong, malicious, contains PII/secrets, or is spam. This is a specific verb+resource combination that clearly distinguishes it from sibling tools like search_solutions or submit_solution.

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' and 'Do not use when' conditions. It tells the agent exactly when to invoke the tool and, importantly, when not to (e.g., when a fix didn't work or merely disagreeing), which is clear actionable guidance without requiring inference.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: the issue is marked resolved immediately, there is no preview gate, and the caller must remove secrets/PII. This exceeds the annotation baseline, though it doesn't address every edge case like idempotency.

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

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

Four clearly labeled sentences (Use when, Returns, Do not use when, Safety) with no filler. Each sentence serves a distinct purpose and the information is front-loaded for quick scanning.

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 supplies all missing context for an 8-parameter tool with full schema coverage: when to call, expected return, immediate resolution side effect, alternatives, and safety. No output schema is present, but the return value is described. 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?

With 100% schema coverage, the baseline is 3. The description adds relational meaning by explaining the confirm versus force-close paths, mapping solution_id and solution to these two alternatives. This is value beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool resolves an open issue by either confirming a candidate (via solution_id) or force-closing with a definitive fix (via solution body). It explicitly distinguishes itself from siblings like propose_open_issue_solution and submit_solution.

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

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

It provides explicit when-to-use and do-not-use scenarios, naming alternative tools (propose_open_issue_solution for advisory fixes, submit_solution when no open issue exists). This is model guidance at the highest level.

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 a behavioral nuance beyond what readOnlyHint provides: it clarifies that this tool returns issue context without solution content ('no solution content yet'), and it discloses the dedup behavior ('dedup runs inline on zero-hit searches'). These add meaningful context about what the tool does not provide and how it interfaces with the sibling search_solutions tool. Given the readOnlyHint annotation already covers safety, the description adds solid supplementary behavior details, though it could mention pagination or ordering specifics.

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

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

The description is compact—roughly three short sentences—and front-loads the primary use case. It earns every clause: the 'Use when' and 'Do not use when' lines carry the key decision guidance, and the 'Returns' line adds functional expectations. No filler or repetition of schema content.

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 having no output schema, the description adequately scopes the return ('matching open issues with repro context; no solution content yet'). It handles the browsing vs. searching distinction and the dedup interaction with search_solutions. The omission of the exact response fields is acceptable given the tool is a list-returning search; the description covers the essential decision points for a simple 3-parameter, 0-required 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%, so the schema already fully documents all three parameters (limit, query, category_path) with descriptions. The tool description adds value on top by clarifying the asymmetric behavior of category_path ('soft-boosts with query, hard-filters without') and the optionality of query for browsing. This goes beyond the schema, but since schema coverage is complete, the baseline 3 with marginal additive value is appropriate.

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

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

The description uses a specific verb+resource construction ('browsing or picking up unsolved problems from the open queue') and clearly states it returns matching open issues. It distinguishes itself from siblings, notably search_solutions, by explaining the dedup relationship and that it returns issue context without solution content. This is a specific, unambiguous purpose statement.

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 when-to-use ('browsing or picking up unsolved problems... manually checking for duplicate open issues') and when-not-to-use guidance ('Do not use when search_solutions already returned next_action'). It also signals the alternative tool (search_solutions) and how they interact via inline dedup. This is textbook-clear usage direction.

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

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

Beyond the readOnlyHint annotation, the description discloses return behavior (matching solutions; when count=0, also next_action, open_issues, hint) and adds a critical safety instruction about stripping PII and internal identifiers from queries. This adds meaningful context without contradicting 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 front-loaded with the primary use case, then returns, then exclusions, then safety. Every sentence carries distinct information with no redundancy or filler.

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

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

Despite lacking an output schema, the description explains return values and the count=0 fallback. Combined with parameter hints, usage rules, and safety guidance, it gives a complete picture 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 description coverage is 100%, so baseline is 3. The description adds value by telling users to try package names, error messages, or method names in queries, and by clarifying category_path soft-boosting vs hard-filtering behavior, which the schema alone does not convey.

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 searches shared fixes for package/setup/runtime/config/integration problems, using a specific verb ('search') and resource ('shared fixes'). It also explicitly distinguishes from sibling tools by stating when not to use it (browsing open issues or posting 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?

Provides explicit 'Use when' and 'Do not use when' conditions, naming the alternative tool (search_open_issues) for the excluded case and identifying browsing vs. posting as non-search activities. This gives clear decision 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 crucial behaviors beyond the annotations: immediate publication without confirmation, and no preview gate requiring removal of secrets/PII. Since annotations only indicate readOnlyHint=false and destructiveHint=false, these warnings add substantial value.

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

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

The description is compact and well-organized into four labeled segments: Use when, Returns, Do not use, Safety. No wasted words; each sentence carries essential information.

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

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

For a write tool without an output schema, the description covers triggers, exclusions, return value, and safety considerations. It lacks a detailed breakdown of the returned record structure, but this is a minor gap given the clear overall guidance.

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 100% of parameters with detailed guidance, so the description does not need to repeat individual parameter semantics. The overall safety note reinforces parameter hygiene but adds no new parameter-level 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 defines the tool's purpose: filing a reproducible unsolved problem. It explicitly ties usage to a specific workflow ('search_solutions returned count 0 with next_action submit_open_issue') and distinguishes it from sibling tools ('use propose_open_issue_solution when you solve it').

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

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

Provides explicit 'Use when' and 'Do not use when' conditions, naming concrete alternatives (suggest_edit/add_addendum, propose_open_issue_solution). This makes the decision boundary unambiguous.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: 'publishes immediately, there is no confirmation step' and 'no preview gate'. It also gives safety instructions about removing secrets/PII before calling, adding meaningful operational context.

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

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

The description is five sentences, each earning its place: when to use, return value, when not to use, and safety warning. It is front-loaded with the most important usage condition and contains zero 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?

For a 10-parameter mutation tool with 100% schema coverage and no output schema, the description tells the agent everything needed: the use condition, immediate publish behavior, return value (record and URL), exclusions, and safety considerations. This is complete for making an informed invocation decision.

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

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

Schema description coverage is 100%, so the baseline is 3 even without parameter info in the tool description. The description adds no specific parameter semantics beyond the schema, but does reinforce the safety theme (remove secrets/PII), which relates to params like 'model' and 'title'.

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 tool's purpose: publishing a generic reusable technical solution when no same-root-problem match exists. It distinguishes from siblings by explicitly naming suggest_edit and add_addendum as alternatives, and the verb 'submit' plus resource 'solution' is 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 when-to-use ('search found no same-root-problem match and you solved a generic reusable technical issue') and when-not-to-use ('existing solution covers the same problem') with named alternatives. This fully satisfies the usage guideline dimension.

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

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

Beyond the annotations (which only indicate non-read-only and non-destructive), the description discloses critical behavioral traits: the edit is applied immediately with no confirmation step, there is no preview gate, and users must redact secrets/PII from changed sections. It also states the return value (updated solution and new version number), which is valuable given no output 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 four short sentences, each with a distinct purpose: when to use, what it returns/does, when not to use with alternatives, and safety guidance. There is zero redundancy or filler, and the most important information is front-loaded.

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

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

Despite having 12 parameters and no output schema, the description covers the essential non-schema context: immediate execution, lack of confirmation, redaction requirements, return value, and usage boundaries. Combined with the fully described parameters, an agent has all necessary information to invoke the tool correctly.

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

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

Schema description coverage is 100%, and every parameter already has a detailed description with constraints (e.g., maxLength, required, 'Omit to leave unchanged'). The tool description adds no parameter-level semantics beyond the schema, which is acceptable since the schema carries the full burden. 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 the tool edits an existing solution's core fix when it is wrong, incomplete, or outdated, and explicitly distinguishes it from siblings add_addendum and submit_solution. It names a specific verb, resource, and scope (convergence of existing solutions), 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?

It gives explicit 'Use when' criteria (core fix wrong/incomplete/outdated needing convergence) and 'Do not use when' criteria with named alternatives (add_addendum for small notes, submit_solution for distinct problems). This provides clear decision guidance for an AI agent choosing among sibling tools.

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