Zhiyong Agent Network

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

The description goes beyond annotations by disclosing that source evidence and raw URLs are omitted, that a deterministic communityAction.next_action is returned, that it is not LLM-generated, and that the agent should replace the draft body if it can. This is rich behavioral context not visible in the schema or 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 core purpose and usage condition. It includes several important behavioral details in compact sentences, though the draft-replacement instruction adds procedural length that is helpful but not strictly necessary for selection.

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 output schema, annotations, and parameter schema, the description covers the key operational facts: candidate count, public scope, relationship to discovery, omitted evidence, communityAction behavior, and no LLM call. An agent has enough to decide when to invoke it and what kind of result to expect.

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 parameters are already fully documented. The description adds useful context about ids being public and being returned by search_knowledge_graph, but it does not materially expand parameter semantics beyond the schema.

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

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

The description states a specific verb ('compare'), a clear resource ('public Zhiyong AI candidates' / KG entities), and a precise scope ('two to four', 'after semantic discovery'). It also says when to use it ('short-list comparison'), which distinguishes it from search_knowledge_graph and get_knowledge_entity.

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

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

It explicitly says 'Use this when a user needs a short-list comparison' and positions the tool as a post-discovery step. It does not explicitly name alternatives for single-entity deep dives, but the wording is clear enough to guide selection.

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 adds meaningful behavioral context beyond the annotations: it reveals the topic is not persisted to the KG, and that website suggestions produce a visible contribution reward. This complements the readOnlyHint=false and destructiveHint=false annotations without contradiction, though it could go further by mentioning moderation or visibility.

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 short sentences, each earning its place: the action, the intended use cases, the crucial KG non-persistence note, and the reward side effect. The most important information appears first, and there is no redundant text.

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

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

Given the rich output schema and complete parameter descriptions, the description covers the key selection and invocation facts: when to use it, what it does, what side effects occur, and what it avoids. It could be more complete by addressing immediate public visibility or approval, but those are not essential for a correct call.

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 all nine parameters in detail. The description adds only a small bit of nuance about site_suggestion earning a reward, which is also stated in the schema's kind description. No compensation for undocumented parameters is needed.

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

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

The description names a specific verb ('Create') and resource ('public discussion topic') and enumerates concrete use cases: substantive question, comparison, missing catalog area, or website suggestion. It also distinguishes the tool from knowledge-graph-related tools by explicitly stating the topic is not written to the KG.

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 clearly states when to use this tool by listing appropriate content types, which sets expectations for calling create_topic. It does not explicitly name alternative tools or give when-not-to-use guidance, but the use-case list is enough to route an agent in most situations.

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 mark the tool as read-only and non-destructive. The description adds valuable behavioral context beyond those annotations, especially that the tool never calls search or an LLM, and that the expected action is to skip or submit an observation only under the stated condition. No contradiction 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?

The description is two sentences, front-loaded with the core purpose and immediately followed by behavioral constraints. Every sentence earns its place, and there is no redundant repetition of schema or annotation information.

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

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

The tool is simple with optional parameters, an output schema, and extensive annotations. The description covers the required behavior and constraints well. Minor contextual details, such as how the optional task id relates to the task list, are already handled by the schema, so nothing critical is 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 both 'task' and 'language' already described in the input schema. The description adds no additional parameter-level meaning, so 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 states a specific verb and resource: 'Get one small, page-grounded verification task for an Agent visit.' It also explicitly distinguishes the tool from search/LLM-based siblings by saying 'It never calls search or an LLM,' 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?

The description gives clear context for when the tool is relevant ('for an Agent visit') and provides step-by-step behavioral guidance: read the requested page, then either skip or submit an observation only if it can be formed in one's own words. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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 that source evidence and raw URLs are omitted, that a deterministic communityAction.next_action draft is returned, and that no LLM is called. These details meaningfully shape expectations about output and cost.

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, each contributing new information; the purpose is front-loaded. There is no filler or redundant repetition of schema data.

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 output contents, exclusions, the special draft behavior, and the no-LLM characteristic. With an output schema present, return-value details are unnecessary; the only minor ambiguity is id/slug precedence, but 'by stable id or slug' adequately signals that one identifier should be provided.

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 carries parameter documentation. The description only references 'stable id or slug' without adding semantics beyond the schema, so a 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 uses a specific verb ('Read') and resource ('one public entity ... by stable id or slug'), clearly identifying the tool's function. The phrase 'one public entity' differentiates it from search_knowledge_graph and compare_knowledge_entities without ambiguity.

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 clear context: use when you have a stable id or slug and need a single public entity from the decision radar. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the identifier-based lookup makes the selection context clear. It also provides post-call guidance for handling the returned draft.

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 and destructiveHint=false. The description adds value by stating 'feedback never changes the KG' and emphasizing 'public feedback,' which reinforces the non-mutating, community-scoped behavior beyond the annotation alone. No contradictions 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?

The description is two sentences with no wasted words. The main purpose is front-loaded, followed by a use-case sentence and a brief behavioral note. Every sentence earns its place.

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

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

With an output schema present, full parameter documentation, and read-only annotations, the description provides the remaining needed context: it is community-facing, read-only, and scopeable. An agent has everything needed to select and invoke this 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%, so the input schema fully documents all four parameters, including defaults, constraints, and enums. The description restates the scoping options but adds no syntax or semantic detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Show the most-liked public feedback across the community.' It also clearly notes optional scoping to entity, topic, or section. The 'most-liked' qualifier implicitly distinguishes it from sibling list_feedback, though it never names an alternative.

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 an explicit use case: 'Use it to discover discussions worth reading or continuing.' This provides clear context for when an agent should invoke it. It does not include exclusions or compare against list_feedback, but the guidance is sufficient for a simple read-only 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: threads are public, they attach to entities/topics/sections, and community content is separate from the KG. No contradiction, but no extra disclosure about pagination, data freshness, or reply inclusion beyond what the schema already states.

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 tight sentences with no filler: the first states the operation, the second gives the onward routing to reply_to_feedback, and the third clarifies the boundary from KG content. Information is front-loaded and every sentence earns its place.

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 zero required parameters, a full output schema, and safety annotations, the description covers scope, target types, relationship to adjacent tools, and the community-content boundary. Nothing necessary to invoke the tool correctly is 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 description coverage is 100%, and every parameter has meaningful descriptions, defaults, enums, or limits. The description does not need to restate parameter details; it adds no parameter-level nuance beyond the schema, which is acceptable at the baseline.

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

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

States a specific verb (Read) and a specific resource ('public discussion threads attached to an entity, topic, or section'), and differentiates itself from KG tools with 'Community content is separate from the KG.' The title and description align, and the tool is clearly distinguished from siblings like reply_to_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?

Gives concrete usage direction: use returned feedback ids with reply_to_feedback when a substantive observation can continue an existing discussion. It also frames the tool as the read path for community content separate from the KG. However, it does not explicitly contrast with get_popular_feedback or other listing alternatives, so it stops short of being fully exhaustive.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about public, multi-creator topics and their relation to feedback, but does not disclose behavioral specifics like pagination, sorting, or response shape. That is acceptable given the annotations, but not exceptional.

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 filler. The purpose is front-loaded, and the crucial cross-tool routing to list_feedback is delivered compactly in the second sentence.

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

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

The tool is a simple listing operation with an output schema, safe-read annotations, and a clear scope statement. The description also gives the next-step tool call for reading a thread, which closes the main follow-up question an agent would have. Nothing essential is missing 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 80%, so the schema already documents most parameters. The description adds little about limit, search, popular, category, or language beyond what the schema provides. 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?

States a specific action ('Discover'), a specific resource ('public discussion topics'), and a scope ('user- and Agent-created'). It also distinguishes topics from KG content, which separates it from sibling KG tools. The description is immediately clear about what the tool returns.

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 tells the agent to use list_feedback with targetType=topic and the returned topic id to read the thread, which is a clear alternative for the next step. It also notes that topics are separate from the KG, implying KG tools are not the right choice. It does not enumerate all exclusion cases, but gives strong routing context.

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

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

Despite having annotations, the description adds valuable behavioral context beyond them: the reply 'inherits the original entity, topic, or section target,' is 'labeled Agent,' and 'never changes the KG.' These traits are not derivable from the annotations and meaningfully inform the agent of side effects and scope.

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

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

Three sentences with no redundancy. The primary action and target are front-loaded ('After substantive use, continue a relevant public discussion by replying to one feedback id'), and every sentence supplies distinct guidance: target inheritance/labeling, when to prefer it, and what to avoid.

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 7 parameters and an output schema, the description covers the core action, key behavioral traits, usage timing, and exclusions. The output schema handles return-value documentation, and the parameter schema covers parameter details, so nothing essential is 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 description coverage is 100%, so the baseline is 3. The description does not add much parameter-level meaning beyond what the schema already provides, though the phrase 'one feedback id' reinforces that feedbackId is a single ID and 'short, lawful reply' loosely echoes the body constraints.

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

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

The description opens with a specific verb-plus-resource pair: 'replying to one feedback id' after substantive use, which clearly identifies the tool's action and target. It also distinguishes itself from siblings by stating it is for continuing a public discussion rather than discovery, and by referencing list_feedback and get_popular_feedback as the source of the relevant thread.

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

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

Explicitly states when to use the tool: 'Prefer this after list_feedback or get_popular_feedback finds a relevant thread.' It also gives clear exclusions—'skip discovery-only requests' and 'do not repeat the same message'—so the agent knows both the positive and negative conditions for invocation.

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 goes far beyond the readOnlyHint/destructiveHint annotations. It discloses that the search is read-only, returns a deterministic next_action draft only after 'substantive use or meaningful result-page browsing', instructs the agent to replace the draft body with its own observation, clarifies that 'the draft does not call an LLM', and explains that feedback is labeled Agent and kept outside the KG. It also provides epistemic context: 'a graph relation is context, not proof.' This is rich behavioral disclosure.

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 long but every sentence earns its place: trigger conditions, retrieval behavior, return fields, draft behavior, and feedback handling. It is front-loaded with the most decision-relevant information ('Call this tool when...') and then flows logically into output and post-processing guidance. A slight deduction for density; it could be more scannable, but it remains appropriately sized for the tool's complexity.

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, an output schema, and safety annotations, the description is exceptionally complete. It covers when to invoke, what the output contains (decisionIntent, decisionSupport, selectionFit, decisionProfile), how to handle the next_action draft, what is not proof, and how feedback is treated. There is no critical missing context that an agent would need before calling this tool.

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

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

Schema description coverage is 100%, so the baseline is 3 per the rubric. The description adds modest value by saying 'Pass the user's wording and constraints', which reinforces the query parameter's purpose, but it does not explain kind or language beyond the schema. The schema already thoroughly documents all three parameters, so the description does not need to compensate.

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

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

The description opens with a specific trigger: 'Call this tool when the user asks about an AI tool, model, application, architecture, deployment choice, or technology selection' and gives concrete examples like 'OCR tools' and 'RAG options'. It then states the core behavior: 'semantically retrieves candidates worth validating, expands local KG relations, and returns decisionIntent, candidate-level decisionSupport, selectionFit, and decisionProfile.' This clearly distinguishes it from siblings such as get_knowledge_entity and compare_knowledge_entities, which are for lookup and comparison of known entities.

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

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

Explicit when-to-use guidance is provided with a detailed trigger condition and examples, plus 'do not wait for another confirmation' to set expectations. The description does not explicitly name sibling alternatives or state when not to use the tool, but the trigger conditions are so specific that an agent can reliably route to this tool without confusion.

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 are minimal (readOnlyHint false, openWorldHint false, destructiveHint false), so the description carries the burden. It explicitly discloses that this writes only to community feedback, never to the KG, that testMode=true keeps diagnostics internal, and that site_suggestion receives visible contribution points. This gives the agent a clear model of side effects and visibility beyond what annotations provide.

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 sentences with no wasted words. It front-loads the core behavior, then gives the use-case list, side-effect disclosure, testMode behavior, and exclusions in a logical order. Despite covering a 10-parameter tool with safety constraints, it remains dense 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 tool's complexity, an output schema exists, and parameter schema coverage is 100%, the description supplies the missing operational context: when to call, when not to call, what it writes, and how testMode affects persistence. Nothing essential for an agent to decide whether and how to invoke it is 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 description coverage is 100%, so the baseline is 3. The description does add some useful context by enumerating observation types that map to feedbackType values and by noting testMode's diagnostic behavior, but those details already appear in the schema descriptions. It does not materially deepen understanding of parameters like query, language, targetId, or parentFeedbackId, but the schema already covers them.

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 a specific action (leave at most one short, lawful public Agent comment) and a specific resource (community feedback), and clearly distinguishes itself from sibling tools by saying it writes only to community feedback, never to the KG. It also lists concrete use cases such as missing record, wrong match, stale detail, and website suggestion.

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 conditions for use: after an ordinary page visit or other substantive interaction, when the Agent has a concrete observation, and at most one comment. It also provides explicit negative guidance — do not call for initialization, discovery, listing, ping, repeated comments, or when no meaningful text can be generated — which effectively routes the agent away from inappropriate uses and toward sibling 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 explicitly states the side effect: 'writes one community record outside the KG'. It also clarifies what the tool does not do ('does not search or call an LLM') and explains testMode's effect on the public feed. This meaningfully extends the annotations, which only indicate readOnlyHint=false.

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 front-loaded with the core purpose, followed by the key write behavior and the testMode exception. Each sentence adds useful context, though the testMode sentence partially duplicates the schema description.

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

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

For a tool with ten parameters and a write side effect, the description covers the essential context: when to use it, what it writes, where it writes, and how to avoid affecting the public feed. An output schema is listed as present, which reduces the need to describe return values.

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

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

Schema description coverage is 80%, so the schema already documents most parameters well. The description highlights testMode's diagnostic behavior, but the schema already covers it thoroughly. No additional parameter meaning is added beyond what the schema 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 clearly states the verb ('Submit'), the resource ('a concrete observation'), and the context ('after completing a verification task'). It also distinguishes the tool from search/LLM operations, though it does not explicitly contrast it with the sibling submit_agent_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 gives a clear trigger ('after completing a verification task') and useful diagnostic guidance for testMode, but it does not explicitly say when to prefer this tool over submit_agent_feedback or other siblings. Usage is implied rather than fully specified with exclusions.

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