Create a project

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

Annotations already declare write/non-destructive/non-idempotent behavior, and the description adds genuinely non-obvious context beyond them: the requestId idempotency-key contract ('reuse it if you retry, so a retry never creates a second project') and the fact that competitor discovery has no dedicated tool. It does not cover permissions/organization scoping or what the call returns, so it falls short of a 5.

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?

Front-loaded with the core action in the first sentence, then workflow and idempotency guidance. It is a dense paragraph rather than a list, but each sentence carries distinct operational value (ordering, sibling names, retry semantics) with little redundancy.

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 no output schema, the description does not need to explain return values, and it covers the creation scope, required inputs at a high level, and the surrounding workflow. What is missing is what the caller gets back (e.g., a project id needed for the follow-up create_tracked_queries call), which an agent orchestrating the sequence would benefit from.

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 only 50%, but the description meaningfully compensates for the undocumented competitors parameter by explaining it needs both suggested names and websites, and clarifies that brandNames are the aliases a brand 'goes by'. The undocumented name and organizationId params remain unexplained, keeping this below a 5.

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+resource ('Create a project that monitors a brand') and scopes exactly what the project contains: website domains, brand names, optional competitors. It also explicitly separates this from the sibling create_tracked_queries ('Tracked queries are added afterwards'), so an agent can route correctly without opening either schema.

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?

Gives explicit sequencing and alternatives: propose everything to the user at once, pull brand names from suggest_brand_names, add tracked queries afterwards via create_tracked_queries, and use list_untracked_competitors after the first checks. It even notes the gap that no tool finds competitors, which prevents the agent from searching for a nonexistent sibling.

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