gc_publishing

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

No annotations are provided, so the description carries the full behavioral disclosure burden. With 9 actions spanning creation (create, post - mutations) and analytics (list, report, compare, trend, funnel - reads), the description gives zero context about side effects, write behavior, idempotency, or what data gets modified. It mentions 'force ingest even if duplicate snapshot exists' only in the schema, not the description. For a tool with multiple mutating actions, this is a significant transparency gap.

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 short and front-loaded with the core concept, but the action list is presented as a comma-delimited catalog that adds noise without explanation. The first sentence is useful; the second sentence is essentially a table of contents that could be derived from the action enum in the schema, providing marginal added value while being technically redundant with the input 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?

This is a highly complex tool (32 params, 9 actions, no output schema, no annotations) but the description gives essentially nothing operational. There's no guidance on which action requires which parameters, no output/return expectations, no mention of prerequisite data (e.g., must create a piece before posting), no error handling notes, and no description of expected workflows. For a tool this complex, the description is drastically under-specified and would leave an agent guessing.

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. However, the description itself adds zero parameter meaning beyond the schema. More importantly, with 32 parameters (many optional, action-dependent), the description does nothing to clarify which parameters apply to which action. The description lists actions but never maps parameters to actions, so an agent cannot know that 'piece_id' is for 'post', 'file' is for 'ingest', 'dimension' is for 'compare', etc. The description fails to compensate for this complexity.

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 says 'Content dissemination metrics' and lists actions, but it reads like a menu or catalog rather than a clear statement of a single cohesive purpose. It's a catch-all tool with 9 different actions and 32 parameters, making the primary purpose ambiguous. It doesn't distinguish itself from siblings like gc_engagement (which likely overlaps with metrics) or gc_work.

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 lists actions (create, post, snapshot, ingest, list, report, compare, trend, funnel) but provides no guidance on when to use this tool versus alternatives. No mention of when NOT to use it, no exclusions, and no context about which sibling tools might be better suited for overlapping tasks like engagement tracking (gc_engagement). The action is exposed as a required parameter but there's no explanation of how actions map to use cases.

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