Reject a knowledge suggestion

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

The description goes materially beyond the annotations: it discloses the endpoint, the required scope (knowledge:write) and OAuth scope, the data-sensitivity label, and the Idempotency-Key requirement with fallback behavior. It also clarifies that the profile itself is not mutated despite destructiveHint=true, which is genuinely useful counter-programming to a scary annotation. It does not say whether a rejection is reversible or what state the suggestion ends up in.

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 behavioral outcome is front-loaded in the first sentence, followed by compact operational metadata. The fixed boilerplate (operation path, scopes, sensitivity) is dense but each line carries actionable information; nothing is padded.

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 need not explain return values, and it covers auth scopes, idempotency, and workspace targeting. The remaining gap is lifecycle context — whether a rejected suggestion can be restored or re-surfaced later — which matters for a destructiveHint=true mutation.

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 75% and the schema already documents workspaceId, workspaceSlug, and idempotencyKey. The description still adds meaning: it explains the workspace override semantics and, more importantly, that idempotencyKey is required by the server and auto-generated when omitted — a behavior not captured in the field description's optional framing.

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 and resource ("Reject a profile suggestion") plus the operational consequence ("so it stops being offered"), which is enough to distinguish it from the sibling luca_knowledge_approve_suggestion by implication. It never explicitly names that sibling, so the disambiguation is inferential rather than stated.

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?

Usage is implied by the paired approve tool and by the sentence about the profile remaining unchanged, which hints this is a no-side-effect-on-data choice. There is no explicit "use this instead of X when Y" guidance, and nothing tells the agent how a rejected suggestion differs from dismissing an insight or rejecting a review queue item.

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