Hedgehog

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. While 'Get' implies a read operation, the description fails to disclose error behavior (e.g., what happens if the spike name doesn't exist), whether the state is cached, or what the state object contains. The existence of an output schema mitigates some need for return value description, but safety and error characteristics are missing.

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 appropriately brief and front-loaded with the core purpose. The Args section provides structured parameter documentation that is easy to parse, though the Python-docstring formatting is slightly informal for an MCP tool description.

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 tool's simplicity (single required parameter, no nested objects) and the existence of an output schema, the description covers the minimum required information. However, it lacks guidance on error states or the nature of the returned state object, leaving minor gaps in contextual completeness.

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% (the 'name' parameter has only a title, no description). The description compensates by documenting the parameter as 'Spike name', adding crucial domain context that identifies what the name refers to within the spike investigation system.

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 clearly states the action (Get) and resource (current state of a spike investigation). It implicitly distinguishes from sibling mutation tools (spike_create, spike_add_branch, etc.) through the 'Get' verb, though it doesn't explicitly state this distinction.

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?

No explicit guidance on when to use this tool versus alternatives like spike_list (which likely lists all spikes) or when retrieval is appropriate versus other operations. The description states what it does but not the contextual trigger for selection.

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