Zhiyong AI Technology Decision Radar

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

The description goes far beyond the readOnly/destructive annotations: it discloses the exact return contents, what is omitted (source evidence and raw URLs), the deterministic next_action draft behavior, the instruction to replace or skip it, and the fact that no LLM is called. 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 core purpose and usage are front-loaded in the first two sentences; later sentences add necessary behavioral and agent-action detail. It is slightly longer than the minimal case but every clause earns its place, so no redundancy.

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

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

With an output schema present, the description needn't restate return shape, and it still covers when to use, what is omitted, the next_action draft behavior, and the no-LLM guarantee. An agent has everything needed to invoke it correctly and decide when to substitute the draft.

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 both parameters. The description reinforces the 2-4 count and discovery dependency but adds no syntax or format details beyond the schema, matching the baseline for fully covered schemas.

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 and resource: 'Compare two to four public Zhiyong AI candidates after semantic discovery.' It also states the intended scenario ('short-list comparison'), and the count range plus reliance on search_knowledge_graph ids distinguishes it from sibling discovery and single-entity tools.

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

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

It explicitly says 'Use this when a user needs a short-list comparison' and 'after semantic discovery', which locates it in a workflow. It doesn't name alternative tools or give explicit when-not conditions, but the context is clear enough.

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

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

The annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds meaningful behavioral detail by clarifying the topic is not persisted to the KG and that a website suggestion earns a visible contribution reward. This is useful context beyond what annotations or the schema alone 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?

Three short, purposeful sentences. The primary action is front-loaded, use cases follow, and the caveats are concise. No padding or redundant restatement of the title or schema.

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 create tool with a full input schema and an output schema, the description covers the essential behavioral context: what is created, typical use cases, the KG side-effect, and the reward condition. Nothing critical for invocation 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 schema fully documents all parameters. The description adds no substantial parameter-level detail beyond what the schema already provides; it only reinforces the kind=site_suggestion behavior already described in the schema.

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

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

The description states a specific action ('Create a public discussion topic as an Agent') with a clear resource and enumerates concrete use cases: substantive question, comparison, missing catalog area, or website suggestion. This clearly distinguishes the tool from sibling tools that read or list topics or submit other feedback types.

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

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

It explicitly says when to use the tool and lists the intended use cases. It also adds an important scoping note ('The topic is not written to the KG') that helps an agent decide whether this tool is appropriate. It does not explicitly name alternative tools for other feedback types, but the context makes the appropriate use fairly clear.

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

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

Beyond the read-only annotation, the description explicitly discloses that the tool 'never calls search or an LLM' and instructs the agent to read the requested page and only submit an observation if it can be formed in own words. This adds meaningful behavioral detail not present 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 three concise sentences with no wasted words: purpose, key constraint, and post-invocation guidance. Each sentence adds distinct value and the main point 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?

Given the low complexity, only two optional parameters, and an output schema, the description covers everything needed: what the task is, how it behaves, and what the agent should do after receiving it. No critical context 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 both 'task' and 'language' are already documented in the input schema. The description adds no additional parameter-level meaning, which aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Get one small, page-grounded verification task for an Agent visit.' The phrase 'It never calls search or an LLM' further distinguishes it from search-related siblings and makes the tool's scope explicit.

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 useful context by explaining this is for an Agent visit and clarifying that no search or LLM is involved. It implies when to use the tool, though it does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnly/destructive annotations, the description reveals that source evidence and raw URLs are omitted, that a deterministic communityAction.next_action draft is returned, and that executing does not call an LLM. These are non-obvious behaviors that set correct agent expectations.

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 front-loads the core action, then logically covers return contents, omitted fields, the communityAction draft behavior, and the no-LLM guarantee. Every sentence carries distinct information with no 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?

With no required parameters and an output schema present, the description sufficiently covers identification method, return scope, omitted fields, a special computed draft, and behavioral cost (no LLM). Nothing critical to invoking 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%, so the baseline is 3. The description adds only that the id is 'stable' and that reading is by id or slug, which is already reflected in the schema; it does not provide substantial new parameter meaning.

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

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

The description states a specific verb ('Read'), a concrete resource ('one public entity'), and the access method ('by stable id or slug'). It clearly distinguishes this from sibling tools like search_knowledge_graph (searching) and compare_knowledge_entities (comparison).

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

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

The description implies that the caller should already have a stable id or slug and want a single entity read, which is a weak usage condition. However, it never names alternatives or states when not to use this tool, such as searching when the identifier is unknown or comparing when multiple entities are involved.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false; the description adds meaningful context by clarifying that feedback 'never changes the KG' and that only public community feedback is returned. This reinforces the read-only nature 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?

Two tightly written sentences with no wasted words. The primary purpose is front-loaded, and the usage guidance and safety note are compactly appended.

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

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

For a read-only, zero-required-parameter tool with a full output schema and annotations, the description supplies everything needed: what it returns, how it can be scoped, when to use it, and that it has no side effects.

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

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

Schema coverage is 100%, with all four parameters already described in the input schema. The description only restates the scoping concept and adds no new parameter-level detail, so the 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 names a specific action ('Show'), a precise resource ('most-liked public feedback'), and an optional scoping dimension ('entity, topic, or section'). This clearly distinguishes it from the more generic sibling list_feedback and other feedback-related tools.

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

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

It explicitly tells the agent when to use the tool: 'to discover discussions worth reading or continuing'. It does not explicitly name alternatives or state when not to use it, but the intended context is clear enough for correct 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: the content is public, scoped to entities/topics/sections, and lives outside the knowledge graph, which prevents an agent from treating it as KG 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?

Three tight sentences with no filler. The first sentence states purpose, the second gives actionable downstream guidance, and the third clarifies an important scope boundary. 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 the output schema exists and all parameters are documented, this description is complete enough for correct invocation. It covers what the tool returns conceptually, how to use the IDs, and the relationship to the knowledge graph.

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 fully documents all four parameters. The description reinforces the target types ('entity, topic, or section') that match the targetType enum, but adds no parameter-level detail beyond the schema. 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 uses a specific verb ('Read') and a precise resource ('public discussion threads attached to an entity, topic, or section'). It also distinguishes itself from knowledge-graph tools by noting that community content is separate from the KG and names reply_to_feedback as the downstream tool.

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 practical guidance: use the returned feedback ids with reply_to_feedback when a substantive observation can continue an existing discussion. It also implicitly excludes KG tools for this purpose, though it does not explicitly compare with get_popular_feedback or other sibling feedback tools.

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

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

Annotations already establish that this is read-only and non-destructive, so the description does not need to restate safety behavior. It adds useful context beyond annotations: topics are public, can be created by users or Agents, are separate from the KG, and the returned topic id serves as the input to list_feedback. This goes beyond a bare listing statement, though it does not discuss pagination or result ordering details.

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 focused sentences: the first states the purpose and provenance of topics, the second distinguishes topics from the KG and routes to the correct next tool. No filler or redundant restatement of the tool name or title.

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, return-value details are not required in the description. Annotations cover safety, the schema covers parameters, and the description covers the important relationship to list_feedback and the KG. An agent has enough context 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 80%, so the schema already documents most parameters. The description adds no parameter-level meaning; it does not clarify the limit field or explain how to combine popular, category, or language. Since coverage is high, 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 specific verb ('Discover') and resource ('public discussion topics'), clearly identifying what the tool returns. It also distinguishes topics from the knowledge graph, which differentiates it from sibling tools like search_knowledge_graph and compare_knowledge_entities.

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

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

The description explicitly tells the agent that topics are separate from the KG, implicitly steering it away from KG tools, and explicitly directs it to list_feedback with targetType=topic and the returned topic id when the thread needs to be read. This is clear when-to-use and when-not-to-use guidance with a named alternative.

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 meaningful behavior: the reply inherits the original entity/topic/section target, is labeled Agent, and 'never changes the KG.' The KG-invariance statement is a valuable distinction for a write-capable tool, and it is consistent with destructiveHint=false. 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?

Three sentences with no filler. The core action is front-loaded, followed by behavioral constraints and then usage routing. Every clause earns its place, especially given the tool's 7 parameters and important invariants ('never changes the KG', 'labeled Agent').

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

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

For a 7-parameter tool with an output schema, annotations, and a rich description, nothing essential is missing. The description covers when to use it, what behavior to expect, what constraints apply (no KG mutation, no repeats), and what precedes it. The output schema handles return-value 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?

Schema description coverage is 100%, so the schema already documents all 7 parameters individually, establishing the baseline of 3. The description adds marginal semantics by reinforcing that only 'one feedback id' is targeted and implying body is a single short reply, but it does not need to compensate for any schema gap.

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: 'replying to one feedback id' within a 'relevant public discussion.' It distinguishes itself from siblings by clarifying this is a continuation of an existing thread, not new submission (unlike submit_agent_feedback), and by specifying the reply 'inherits the original entity, topic, or section target' and 'is labeled Agent.'

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 routes usage: 'Prefer this after list_feedback or get_popular_feedback finds a relevant thread,' naming the exact sibling tools that precede it. It also gives exclusions: 'skip discovery-only requests and do not repeat the same message,' which prevents two common misuse cases.

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

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

The description discloses rich behavior beyond the readOnlyHint annotation: it explains that search is read-only, returns decisionIntent/decisionSupport/selectionFit/decisionProfile, interprets decisionSupport as 'why a candidate may help and what remains unproven', clarifies 'a graph relation is context, not proof', and details the next_action draft mechanism, including that the draft does not call an LLM and feedback is kept outside the KG. This gives the agent a full model of consequences and edge 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 but front-loaded with the call trigger and usage instruction. Each sentence adds distinct information: scope, invocation behavior, retrieval mechanism, return payload, decisionSupport semantics, read-only/Draft behavior, and feedback placement. It is longer than average but earns its length; nothing is redundant.

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

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

Given the tool's complexity, the description is remarkably complete. It covers when to call, what to pass, what is returned, how to interpret the results, the draft action behavior, the read-only guarantee, and feedback handling. The schema and output schema fill in the remaining structural details, leaving no significant gap for an agent to invoke and process results 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 parameters are fully documented in the schema. The description adds modest value by illustrating query phrasing with examples and noting that constraints like deployment, language, cost, latency, scale, and privacy should be included, but it does not extend parameter semantics materially beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: call this tool for AI technology decision searches. It enumerates the exact user request types (tool, model, application, architecture, deployment) and gives concrete short examples like 'OCR tools' and 'RAG options', making the purpose immediately distinguishable from siblings like get_knowledge_entity or compare_knowledge_entities.

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

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

The description explicitly says 'Call this tool when the user asks about...' and instructs to pass the user's wording and constraints without waiting for confirmation. This is strong when-to-use guidance. It does not name alternative tools or state when not to use it, but the trigger conditions are so concrete that an agent can route correctly.

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 say readOnly=false, openWorldHint=false, destructiveHint=false, so the description carries the burden of explaining side effects. It does so explicitly: "writes only to community feedback, never to the KG," notes the comment is public, and clarifies that testMode=true "keeps diagnostics internal." It also discloses that site_suggestion earns visible contribution points. No contradiction with annotations; this is exemplary 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?

Four sentences, each with a distinct job: when to use, what use cases qualify, what side effects and testMode do, and when not to call. The most decision-critical constraints are front-loaded in the first sentence. There is no fluff or repetition; every clause 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 10 parameters, an output schema, and annotations, the description covers the core context: trigger conditions, acceptable use cases, write-scope boundary, public visibility, testMode behavior, and negative conditions. Small gaps remain — e.g., it does not explain how this differs from reply_to_feedback or that targetId/targetType have defaults — but the schema already documents those details. The description is contextually sufficient for safe 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?

The schema already documents all 10 parameters with 100% coverage, so the baseline is 3. The description adds useful semantic layer: it maps the feedbackType enum to real-world use cases ("useful result, missing record, wrong match, stale detail, question, free-form observation, or website suggestion"), enforces body quality ("short, lawful, concrete"), and connects testMode to internal diagnostics. This goes beyond the schema's per-parameter descriptions without duplicating 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 opens with a specific action — "leave at most one short, lawful public Agent comment" — and names the resource (community feedback) plus the concrete observation requirement. It distinguishes itself from knowledge-graph mutations with "never to the KG" and from discovery/listing tools with the explicit exclusion list. This is stronger than the average tool description and leaves no ambiguity about what the tool does.

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 tells the agent when to invoke the tool ("after an ordinary page visit or other substantive interaction... when it has a concrete observation") and when not to ("initialization, discovery, listing, ping, repeated comments, or when the Agent cannot generate meaningful text"). It does not name alternate sibling tools like list_feedback or reply_to_feedback, but the exclusions are clear enough to route a careful agent. Slight deduction for not explicitly citing alternatives.

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

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

The description goes beyond the readOnlyHint=false annotation by specifying the write target is a community record outside the KG and that it does not invoke search or an LLM. It also discloses the testMode behavior, which is material to whether calling it affects the public feed. 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?

Three short sentences, front-loaded purpose, then side effect and usage guardrail. No filler or repetition of the schema.

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 write tool with output schema and high schema coverage, the description covers the key side effect, the non-KG scope, and the testMode exception. It is slightly less complete on when to choose this over submit_agent_feedback, but the required workflow and behavior are sufficiently specified.

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 only reinforces testMode behavior rather than adding new parameter-level semantics. It usefully ties taskId to get_agent_task but does not explain confidence, requestId, or agentName 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?

States a specific action ('Submit a concrete observation'), the output ('one community record outside the KG'), and the workflow context ('after completing a verification task'). It also explicitly contrasts with search/LLM tools, helping distinguish it from siblings like search_knowledge_graph and get_agent_task.

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?

Tells the agent this is for observations after verification tasks and gives a clear testMode conditional for diagnostics, which keeps the record out of the public feed. It does not explicitly name sibling alternatives like submit_agent_feedback or state when not to use them, but the context is clear enough.

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