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

Annotations already flag destructiveHint=true and openWorldHint=true, so the description goes further by disclosing cost (1 db credit), an auth prerequisite (StartupHub.ai account), and the effect on listing visibility. The note that an edit 'does not hide' the profile is useful context, though it sits in mild tension with the destructive annotation and could be read as reassurance about data loss rather than listing state.

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?

Short, front-loaded, and telegraphic, with the action and the required slug up front. 'The profile stays on the free listing' and 'An edit does not hide it' restate the same idea twice, which is the only waste.

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 10-parameter mutation tool with annotation coverage of the safety profile and no output schema, the description supplies the essentials: partial-update behavior, cost, auth, and listing effect. Return values are not described, but with no output schema that is not required.

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 0% across 10 parameters, so the description carries the burden, yet it only names 'slug' and establishes partial-update semantics. The remaining fields (city, country, avatar_url, github_url, twitter_url, linkedin_url, website_url, current_title, description) are self-describing by name, which partially offsets the gap, but no format or validation detail is added.

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 ('Update a person you previously submitted'), which cleanly separates it from siblings like submit_person or search_people. It does not explicitly name the sibling tools (update_startup, update_investor), so it falls short of a 5.

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?

'Pass slug plus only the fields to change' gives concrete invocation guidance and implies a partial-update model. Preconditions (free account, 1 db credit) are stated, but there is no explicit when-not-to-use or routing to an alternative tool.

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