search_decisionsQuery accepted or proposed decisions and constraints using BM25 to find relevant ADR-style records, with optional status filter or inactive inclusion.
BM25 search across decisions and constraints. Active (accepted/proposed) only unless include_inactive or status is set.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| query | Yes | ||
| status | No | ||
| include_inactive | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the default active-only filtering and how include_inactive/status override it, which is real behavioral context. It says nothing about ranking behavior, result caps, or permissions, leaving significant gaps for a read tool.
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?
Two short sentences, no filler, and the search mechanism plus the default-scope caveat are both front-loaded before any agent needs to open the schema.
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 annotations, no output schema, and 0% schema description coverage on five parameters, the description should do more. It adequately covers default filtering and two of the five parameters but omits limit behavior, ranking/pagination, and any return-shape expectations.
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% across five parameters, so the description must compensate and only partly does: it explains include_inactive and status semantics and implicitly maps 'decisions and constraints' to the type enum. The limit cap and the required query parameter's expected syntax are left undocumented.
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 (BM25 search) over a specific resource (decisions and constraints), which clearly separates it from write siblings like record_decision and supersede_decision and from the plain list_constraints enumerator. It does not explicitly name an alternative, so it stops 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?
The default filter clause ('Active (accepted/proposed) only unless include_inactive or status is set') tells the agent the conditions that broaden results, which is useful implied guidance. However, there is no explicit statement of when to search versus when to use list_constraints or get_context_for_task, so usage is only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.