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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds the crucial context the annotations cannot: the submission is 'irreversible,' what it contains (feedback, operation IDs, account contact/reference identifiers), the required user consent flow, and post-call guidance. It also discloses the important boundary that low-level passthrough operations (gads_mutate, meta_ads_update_adset) return platform responses, not Markifact's, so they shouldn't be reported here.

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?

Long but front-loaded and organized: purpose, when-to-call, consent conditions, behavioral/disclosure notes, scope exclusions, content hygiene, and return value all in distinct paragraphs. It is longer than strictly necessary and could shed a little redundancy, but every paragraph earns its place given the consent and safety stakes.

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 destructive, open-world, non-idempotent submission tool with an output schema present, the description is essentially complete: it covers authorization, irreversibility, payload contents, scope boundaries, sensitive-data rules, and a brief return-value note. Since an output schema exists, it needn't detail return structure further.

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 real value beyond the schema: it requires title and description in English, instructs including only minimum non-sensitive evidence, forbids secrets, and warns to avoid duplicate reports and use 'other' only when no other category fits. It doesn't walk through all five params, but it meaningfully enriches the key content and category fields.

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?

Explicit verb+resource: 'Submit actionable product feedback to Markifact.' It clearly distinguishes itself from siblings, which are all operation-discovery and execution tools (find_operations, run_operation, etc.), none of which submit feedback. An agent can select this without ambiguity.

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?

Unusually strong. It states the trigger condition ('When you encounter a likely Markifact bug, missing capability, or product limitation'), the two precise authorization gates for calling, explicit anti-patterns ('Do not call this tool merely to ask for permission,' 'do not submit feedback silently'), and exclusions ('Never report third-party policies, outages, rate limits...'). It even routes capability questions to the normal operation discovery flow rather than testing by executing a write.

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