research_publish_knowledge

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

The description explains that the tool projects a reviewed ResultClaim into deterministic Evidence)Skip and publishes it directly, and that the action is idempotent with no separate confirmation required. This aligns with and adds context beyond the idempotentHint annotation fran. It does not cover permissions or failure behavior, but the annotations already signal non-read-only and non-destructive 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 every sentence earns its place: it front-loads the tool's mandatory role, then explains ordering, task_id selection, action semantics, and idempotence. There is no filler or repetition beyond what is structurally necessary for the complex workflow.

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

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

For a high-complexity workflow tool with no output schema, the description covers the key invocation context, parameter semantics, action variants, and idempotence. It does not describe return values, possible errors, or what happens if the latest ResultClaim is not acceptable, but it explicitly says no confirmation is required, which reduces that ambiguity.

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

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

With 0% schema description coverage, the description carries the full burden for parameters. It explains task_id must be the latest execution task UUID, specifically the latest executionTaskIds entry or ResultClaim.executionTaskId, and never the research cycle UUID. It also gives semantic meaning to both action enum values and specifies that a non-empty reason is needed for NO_KNOWLEDGE_TO_PUBLISH.

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

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

The description clearly defines this as a required post-result publishing step, with a specific resource ('publish it directly to the authoritative Knowledge Graph') and two concrete action modes. It also disambiguates its position in the research cycle by stating it runs after RESULT_REVIEW and before follow-up decisions or cycle closure.

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 ordering conditions: call after an accepted settled RESULT_REVIEW and before follow-up decisions, next-experiment proposals, cycle closure, or linked execution. It also gives clear conditional guidance for NO_KNOWLEDGE_TO_PUBLISH. It does not explicitly name alternative sibling tools, so the boundary is clear in pipeline terms but not tool-comparison terms.

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