HubSpot MCP Server

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

With no annotations provided, the description carries the full burden of behavioral disclosure but provides almost none. 'Search notes with specific filters' doesn't indicate whether this is a read-only operation, whether it has side effects, what authentication might be required, rate limits, pagination behavior (though the schema has 'limit' and 'after' parameters), or what the output looks like. For a search tool with complex filtering capabilities, this minimal description fails to provide essential behavioral context.

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 extremely concise at just 5 words. While this brevity comes at the cost of completeness, it's efficiently structured with zero wasted words. The single sentence directly states the core function without unnecessary elaboration, making it front-loaded and easy to parse despite its inadequacy in other dimensions.

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?

Given the complexity of the input schema (5 parameters with nested objects, complex filtering logic, sorting, pagination) and the complete absence of both annotations and output schema, the description is woefully incomplete. 'Search notes with specific filters' doesn't prepare an agent for the sophisticated filtering system with multiple operators, property-based queries, or the pagination mechanism. For a tool with this level of parameter complexity and no structured documentation elsewhere, the description provides almost no useful context.

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?

The schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The tool description 'Search notes with specific filters' only vaguely hints at the 'filterGroups' parameter but provides no meaningful semantic information about any parameters. It doesn't explain what 'properties' returns, what 'sorts' does, how 'limit' and 'after' work for pagination, or the complex filter structure with operators and property names. The description fails to compensate for the complete lack of schema descriptions.

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 'Search notes with specific filters' is a tautology that essentially restates the tool name 'notes_search'. It provides the basic verb+resource ('search notes') but lacks specificity about what kind of search this performs or how it differs from other note-related tools like 'notes_list' or 'notes_get' in the sibling list. The description doesn't distinguish this tool from its siblings beyond the obvious name difference.

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 provides absolutely no guidance on when to use this tool versus alternatives. With multiple note-related tools available (notes_list, notes_get, notes_search, notes_create, notes_update, etc.), the agent receives no indication about what makes this search tool appropriate for certain scenarios or what its limitations might be. There's no mention of prerequisites, typical use cases, or comparison to other tools.

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