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

Annotations already mark this as destructive, and the description adds substantial behavioral detail: it overwrites profile facts, leaves unsupported fields unchanged and never nulls them, stamps profileSyncedAt, leaves the niche untouched, and is rate-limited with an error naming the wait time. This is exactly the kind of context that helps an agent predict side effects.

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 four purposeful sentences, front-loaded with the core behavior and followed by trigger, side effects, and rate-limit behavior. Every sentence adds unique information and there is no repetition of the tool name or title.

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 mutating tool with no output schema, the description covers the trigger, what gets overwritten, the preservation rule, untouched niche, timestamp stamping, and rate-limit error behavior. An agent has enough context to decide when to call it and what to expect on both success and cooldown paths.

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%, so the description needed to explain projectId, but it never mentions the parameter. The schema's property name and UUID format are self-evident, but the description adds no semantic guidance about how to obtain or use the projectId. With only one parameter, the gap is not fatal, but it is still a real compensation miss.

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 names a specific action ('re-read the project website and re-infer the asset profile'), the exact resource affected, and the fields involved. It also distinguishes this from related tools by stating that it derives facts from current site content and does not touch the niche.

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 a precise trigger: 'Use before rendering a report when get_pitch_report_payload flags assetProfile.syncedBeforeRun.' This is strong when-to-use guidance with a rationale. It does not explicitly name alternatives like update_asset_profile or state when-not-to-use, so it falls just short of fully explicit sibling differentiation.

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