Zhiyong AI Technology Decision Radar

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

Annotations already mark the tool as read-only and non-destructive, and the description adds concrete behavioral detail: decisionProfile dimensions, public metadata, known notes, typed relations, omission of source evidence and raw URLs, and the fact that it does not trigger another search or LLM call. It also conditions a post-comparison action. 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 front-loaded and each sentence provides useful information. It is slightly dense toward the end, especially the undefined interactionContract instruction, which prevents the highest conciseness score.

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 and annotations, the description sufficiently covers returns, omissions, when to use, and side-effect behavior. The remaining ambiguity is what interactionContract contains and how the post-comparison reply/feedback action should be invoked, which is only partly resolved by sibling tool names.

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 ids and language. The description adds only that the entities are public candidates and that comparison involves a short-list, which maps to ids but does not meaningfully extend parameter understanding.

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 (compare), the resource (public Zhiyong AI candidates), and the scope (two to four entities, short-list comparison). It positions the tool relative to search by saying 'after semantic discovery', though it does not name sibling tools explicitly.

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 places the tool after semantic discovery. It does not name alternatives or state when not to use it, so the guidance is clear but not complete on exclusions.

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

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

The description goes beyond the annotations by disclosing that the topic is not persisted to the KG and that a website suggestion yields a visible reward. Side-effect and persistence behavior is therefore reasonably transparent, though rate limits or auth requirements are not mentioned.

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 are front-loaded: the operation, its intended use, a key non-obvious behavior, and a special-case consequence. No filler, no restating parameter names.

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 9 parameters, a full schema, and annotations indicating a non-read-only external write, the description provides enough invocation context: what the topic is, what kinds of content belong, that it does not touch the KG, and the reward side effect. It doesn't mention exclusions or alternatives among the sibling tools, but the core usage context is complete.

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

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

The input schema already covers all parameters with 100% coverage, including the site_suggestion reward behavior. The description reinforces this but does not add meaningful parameter-level detail 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 names a specific action and resource ('create a public discussion topic'), lists concrete use cases (question, comparison, missing catalog area, website suggestion), and clarifies the topic is not written to the KGhe differentiating it from knowledge-graph operations. This is clear enough to pick the tool confidently.

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 scenarios for when to use the tool and mentions a distinct behavior for website suggestions. It does not explicitly state when not to use it or how it compares to sibling feedback/observation tools, so it lacks an exclusionary guideline.

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=true annotation, the description is transparent: it lists what is returned, what is omitted ('source evidence and raw URLs are omitted'), and claims it triggers no side effects. This adds genuine behavioral context to safe hook, such as the fact that it makes no deeper search/LLM call, which an agent can't infer from 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 first sentence is front-loaded and complete; the second adds workflow guidance; the third is short. Though the interactionContract sentence is dense and adds extra steps, no sentence is padding. It is fit for a read tool with non-trivial follow-up semantics.

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 anoutput schema, the description does not need to specify return fields, but it supplies important context: response-field boundaries (omitted evidence/URLs), language override, and business rules around when to write. It is complete enough for an agent to correctly decide to use and interpretation 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 structured data already fully documents id, slug, and language. The description adds the phrase 'by stable id or slug,' which is redundant rather than new meaning. With the schema already carrying the parameter details, 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 uses a precise verb ('read'), names the resource ('one public entity from Zhiyong AI's decision radar'), and lists the return contents via stable id/slug. This clearly distinguishes it from the search-oriented sibling search_knowledge_graph, which targets arbitrary querying rather than single-entity retrieval.

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 states clear context: use it to read a specific entity and, after doing so, conditionally perform a reply/feedback action. It also clarifies what it does not do ('does not trigger another search or LLM call') and instructs skipping otherwise. However, it never names comparator siblings like search_knowledge_graph or compare_knowledge_entities, leaving the when-to-use-vs-alternatives routing implicit rather than explicit.

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?

While annotations indicate readOnlyHint=true and destructiveHint=false, the description adds context by noting that reading is free of search and LLM calls, which is useful behavioral information. However, it does not disclose potential pagination or rate-limit behavior beyond the schema's limit parameter. The description does not contradict 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 filler. The main purpose is front-loaded, and the usage guidance is concise. Every sentence adds value, making it both streamlined and informative.

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

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

The description is nearly complete for a read-only tool. It covers purpose, usage, and even hints at cost implications. The output schema exists, so return values are documented. Minor omission: it doesn't state that the tool sorts or filters results, but given the simplicity and available schema, this is acceptable. Could specify interaction with other siblings like get_popular_feedback.

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 already covers all parameters with descriptions (coverage 100%). The description adds no extra parameter-specific details beyond what the schema provides, but it does contextualize targetId and targetType by explaining they refer to feedback threads attached to different target types. Since the schema is comprehensive, a 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 function: reading public discussion threads attached to an entity, topic, or section. It distinguishes itself from siblings by specifying the resource (feedback threads) and the action (list/read). The mention of using returned feedback ids with reply_to_feedback further clarifies its role in the broader 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 when to use this tool compared to reply_to_feedback: 'Use the returned feedback ids with reply_to_feedback when a substantive observation can continue an existing discussion.' This provides clear routing guidance, and the description also notes that reading is free of search and LLM calls, which is a key selection criterion.

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?

The description directly contradicts the annotations. The annotations declare 'readOnlyHint: false', implying the tool may modify data, but the description states 'never changes the KG' (knowledge graph). Additionally, the description mentions 'does not trigger search or an LLM call,' which is useful behavioral context, but the contradiction about mutability is a severe inconsistency that could mislead an agent into thinking the operation is safe when the annotation flags otherwise.

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 yet information-dense, spanning three sentences without redundancy. It begins with the core action, then specifies inheritance and non-mutability, and ends with usage criteria and exclusions. The structure effectively front-loads critical information while avoiding unnecessary elaboration.

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 many necessary aspects, such as when to use, exclusions, and the non-search behavior, and the schema handles parameter details. However, the contradiction about modifying the knowledge graph severely undermines completeness because an agent cannot rely on the described behavior versus the annotation. This inconsistency creates ambiguity about the tool's actual side effects, making it incomplete for reliable decision-making.

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 7 parameters are documented with 100% schema coverage. Required parameters feedbackId and body have clear descriptions: feedbackId is 'The public feedback id returned by the feedback list or a previous feedback action,' and body is 'One short, lawful reply' with length constraints. Optional parameters like language and feedbackType benefit from enums and explanations, making selection unambiguous.

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 function: 'continue a relevant public discussion by replying to one feedback id.' It specifies the resource (feedback) and the action (reply), and explicitly distinguishes itself from siblings like list_feedback (listing) and submit_agent_feedback (submitting) by emphasizing it continues an existing discussion. The mention of 'inherits the original entity, topic, or section target' further clarifies its scope.

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 when-to-use guidance: 'Prefer this when interactionContract or list_feedback finds a relevant thread.' It also states exclusions: 'Skip discovery-only requests and do not repeat the same message,' and clarifies that it does not trigger search or an LLM call, which helps agents decide between this and other tools like search_knowledge_graph.

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 beyond readOnlyHint=true to explain that the search returns candidates, not proof ('a graph relation is context, not proof'), and that the interactionContract step does not trigger additional calls or writes. This adds concrete behavioral context beyond the annotations, clarifying safety and follow-up 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 dense and long, mixing invocation guidance, return-value semantics, and post-search interaction instructions (interactionContract) that are not part of invoking this search tool. Important guidance is spread across many clauses, making it harder to parse quickly. The first sentence is strong and front-loaded, but the middle sections about decisionSupport semantics and public writes are off-topic for tool 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?

The description covers query phrasing, constraints, entity types, return semantics, and exclusions/skip conditionsarenas. It goes beyond what the schema and annotations provide recursive. However, it overloads the description with post-invocation interactionContract details that belong in the output schema or a follow-up tool description rather than the search tool's own description.

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 explains the parameters. The description further clarifies usage by explaining how to phrase the query, that constraints are auto-detected, and that OCR/PDF candidates are typed as model (directly relevant to the kind parameter). This adds real semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: searching for AI tools, models, and technology decisions when a user asks. It explicitly lists the kinds of queries it handles ('OCR tools', 'RAG options', 'open-source MoE models'), and mentions the entity-type filter for navigating KG typing quirks. This distinguishes it from siblings that focus on specific tool details or trending topics.

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

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

The description explicitly states when to call ('Call this tool when the user asks about an AI tool...'), what to pass ('Pass the user's wording and constraints'), and when to skip ('Skip only for discovery-only requests, client write restrictions, or no grounded observation'). It also clarifies not to wait for confirmation, reducing ambiguity for an agent.

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

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

Beyond the annotations, the description discloses important side effects: it writes only to community feedback, never to the KG, does not trigger search or an LLM call, and awards visible contribution points for site_suggestions. This is exactly the behavioral context an agent needs and is not redundant with the 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?

Every sentence earns its place: the first front-loads the trigger and constraint, the second lists valid use cases and incentives, and the third captures side effects and exclusions. No filler or repetition.

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 exists and the input schema fully documents parameters, the description supplies the remaining context: when to call, what counts as valid feedback, side effects, and when not to call. An agent can decide and invoke this tool correctly without further documentation.

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 has 100% coverage and documents all parameters, including enums, defaults, and the contribution-points behavior of site_suggestion. The description echoes that information without adding new parameter-level semantics, so the 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 action: submit at most one short, lawful public Agent observation for specific task contexts, and enumerates valid use cases. It is not a tautology and differentiates from generic feedback by scoping to post-task observations, but it does not explicitly contrast with the sibling submit_agent_observation.

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 trigger conditions ('After a real search, entity read, comparison, or grounded page-verification task') and explicit negative conditions ('Do not call it for initialization, discovery, listing, ping, repeated comments...'). It lacks named alternative tools, so it falls short of a full 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?

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.