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

Annotations only declare it is a non-read-only, non-destructive, closed-world write; the description adds substantive behavior beyond that: items are stored as 'Claimed', re-recording the same URL updates rather than duplicates (upsert semantics), verification costs 1 credit, and Claimed items are re-checked daily for free for 30 days. It does not describe failure modes or what the response returns, but the credit and lifecycle details are valuable.

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 purpose is front-loaded in the first clause, but the body is a chain of run-on sentences that mixes artifact typing, credit pricing, re-check cadence, upsert behavior, and cross-tool flows without paragraphing. Nearly all content is useful, yet the density hurts scanability for an agent parsing it.

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 6-parameter mutation tool with a nested free-form 'meta' object, no output schema, and 0% schema coverage, the description covers lifecycle and cross-tool flow well but leaves module selection and title conventions undocumented. An agent could still call it, but would be guessing on two required parameters.

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 0% across 6 parameters, so the description carries the burden. It does explain url vs liveUrl per kind and meta.fixIds for site fixes, and implies the kind values by enumerating artifact types. However, the 9-value 'module' enum and 'title' (min 3 / max 200) get no explanation at all, leaving meaningful gaps.

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 concrete verb+resource: 'Report anything you shipped with the founder,' then enumerates the accepted artifact types (PR, live page, listing, index request, post, Gmail draft). An agent can tell this is a write/record tool distinct from siblings like 'shipped' or 'verify', though the phrasing is conversational rather than crisp.

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 gives real routing guidance: call verify to check a Claimed item (1 credit), use record_merges to confirm private-repo PR merges, and record listings on the directory submit/account page so they wait as 'submitted'. It stops short of explicit when-not-to-use or prerequisites such as workspace scope, so it is strong but not exhaustive.

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