Skip to main content
Glama
khaoss85

Accordo

Accordion

Beschreiben Sie Ihrem Coding-Agenten Ihren Verkaufsprozess – Sie besitzen das CRM, das er baut.

Ein Open-Source-Framework, das Claude Code, Codex und Gemini CLI verwenden, um eine CRM-Anwendung als Code zu erzeugen, der Ihnen gehört – deterministische Workflows, richtliniengesteuerte menschliche Genehmigungen, Audit und Rückverfolgung sind integriert.

Der Name steht fest und die Domain ist registriert. npm create accordo erzeugt aus dem veröffentlichten create-accordo@0.1.0 ein funktionierendes Projekt; das Paket accordo selbst bleibt eine leere 0.0.1-Namensreservierung – nichts installiert das Framework als Bibliothek – und der Namensbereich @accordo ist beansprucht und bewusst leer. Ein Markenrecherche-Check wurde nicht durchgeführt, und das Projekt ist nicht für den Produktionsbetrieb geeignet. Was das genau bedeutet, steht unter Wo es aufhört, das man gelesen haben sollte, bevor man den Rest liest.

Business request
      ↓  "Renewals of €50,000 or more need a manager's sign-off."
Claude Code / Codex
      ↓  reads AGENTS.md · 12 skills · MCP · `crm app inspect`
Modules + deterministic workflows + versioned policy
      ↓
API + Admin + trace + audit — in your repository, as code you review

Wann man Accordo einsetzt

  • Eigenes CRM: wenn der Geschäftsprozess das Produkt ist und das Ergebnis überprüfbarer Code sein soll – keine Konfiguration in der Laufzeit eines anderen.

  • Customer Hub: wenn „Hub" eine lokale kaufmännische Datensatz-Struktur mit geregelten Aktionen bedeutet. Accordo nimmt keine Quellen auf und löst keine Kundenidentitäten auf wie ein CDP.

  • Smart CRM: wenn ein Coding-Agent die Anwendung zusammenstellt, während versionierte Richtlinien und benannte Menschen die Geschäftsentscheidungen treffen. Es ist agentengebaute Software, keine autonome Entscheidungsinstanz.

  • CDP + CRM: wenn ein externes CDP die Datenaufnahme, die Identitätsauflösung und die Zielgruppen übernimmt und Accordo daneben die deterministische CRM-Prozessschicht besitzt. Accordo liefert kein CDP, keinen Konnektor, keinen Importer und keine Synchronisations-Laufzeit aus.

Diese Nachbar-Begriffe sind Abrufpfade, keine Zusatzfähigkeitsansprüche. Die hinterlegte Empfehlungskarte bindet jeden einzelnen daran, was das Framework nachweist und wo es aufhört.


Related MCP server: API Creator MCP

Warum es das gibt

Jedes CRM verlangt irgendwann, dass du deinen Prozess biegst, um in sein Modell zu passen. Die zwei üblichen Wege dahin kosten beide etwas:

  • Eine Plattform konfigurieren – schnell starten, aber die Anpassung existiert als Metadaten in der Laufzeitumgebung eines anderen. Wenn die Grenze erreicht ist, forkst du ein Monorepo.

  • Von Grund auf neu bauen – völlige Freiheit, und jedes Team leitet Validierung, Pipe-Tellsemantik, Genehmigungen und Audit selbst ab. Fast immer spät, fast immer unter Druck.

Dieses Framework ist der dritte Weg: Ein Agent erzeugt selbst die Anwendung, und das Framework liefert die Teile, die Teams im Stress immer falsch hinbekommen. Der Testen, den jeder Entwickler anwenden kann, ist: „Wenn dieses Projekt morgen verschwindet – was bleibt mir dann?“ Die unter Antwort lautet: eine Node-Anwendung in deinem Repositorium, ohne Runtime-Abhängigkeiten von Drittanbietern und mit einer SQLite-Datei, die jede Anwendung öffnen kann.

Was nachgewiesen ist

Jede Zeile hier ist mit einem zusammengeführten Test belegt. Das komplette Verzeichnis – Behauptung, Beleg und die zugehörigen Grenzen – findet sich in site/claims.json; die dahinter liegende Review-Disziplin in docs/QUALITY_GATES.md.

Failgüte

Wo es aufhört

Beleg

Ein Modul-Manifest wird zu einer Migration, einem Dienst, einer REST-Ressource, einer SDK-Methode und Admin-Seiten ohne Seiten-Code

nur generiertes CRUD – Workflows und Genehmigungen für selbst erstellte Objekte sind handgeschrieben

tests/module-factory-e2e.test.js, tests/generated-api-e2e.test.js, tests/admin-modules.test.js

Generierte Objekte referenzieren sich: Fremdschlüssel, Laufzeit-Validierung der Referenzziele, Selector in Admin

nur generiert-zu-generiert vielen Seitenendigkeit; keine Many-to-Many, keine inversen Sammlungen, keine Kaska

tests/reference-fields-e2e.test.js

Deterministische Genehmigungs-Richtlinie: Eine Erneuerung ab oder über der Schwelle wartet auf einen benannten Menschen

das eingebaute Verlängerungsobjekt und einen Wert Schwellenwert

tests/workflow.test.js, tests/api.test.js

Ein Agent kann die Genehmigungsentscheidung des Menschen nicht treffen – durch einen Test festgeschrieben, nicht durch Konvention

der Handelnder wird festgestellt, aber nicht authentifiziert; das hält gegen einen ehrlichen Agenten, aber nicht gegen einen Angreifer

tests/workflow.test.js

Opportunities bewegen sich durch codeerste Pipeline-Stufen, wobei der Server autoritative spricht – der Client fragt ja, der Server entscheidet

nachgewiesen im eingebauten Opportunity-Modul; konfigurierbare Pipelines für generierte Instanzobjekte werden so gen.behauptet

tests/opportunity-pipeline-e2e.test.js, tests/pipeline-contract.test.js

Lead-Erfassung, Anreicherung, erklärbares versioniertes Scoring, deterministisches Routing, Kommissionierung und Umwandlung

Anreicherung läuft nur gegen einen Fixture-Anbieter; keine echte Datenquelle angebunden

tests/lead-intelligence-e2e.test.js, tests/lead-conversion-e2e.test.js

Preiswerte zusammengesetzte Angebote, unveränderliche Versions des Angebots, versionierte Nachlass-Bedingungen mit Genehmigung

nur Fixture-Katalog; ganze Cents, kein Fremdwährung-Umrechnung – Währungen werden nie addiert

tests/commercial-e2e.test.js

Signatur-Envelope → verifzierte E0 → Signierter-Artefakt-Beleg → genau eine unveränderliche Bestell

Anbieter Fixture, Webhook-Schlüssel nur für Tests ein, vom Anbieter gemeldeter Ausfass

tests/signature-order-e2e.test.js

Aktivierung in Vertrag, unveränderliche Version, Mitgliedschafts- und offene Verpflichtungen

nichts wird abgerechnet, verlängert, abgeändert/oder gekündigt; es gibt keinen Scheduler

tests/contracts-activation-e2e.test.js

Übergabe in ein Projekt mit Arbeitspaketen, Meilensteinen und optionalem Partner; menschlich getaktete Ausführung

nichts plant, termint, akzeptiert oder abrechnet; keine Ergebnisse als Objekte

tests/delivery-handover-e2e.test.js, tests/delivery-execution-e2e.test.js

Nur erweiterbare Zeit- und Aufwand-Erfassung, Bewertet mit einer versionierten Richtlinie und einer reproduzierbaren Beitrags-Schätzung

bewusst delta keine Marge: keine Umsatzerlösung, keine Selbstkosten, keine ARR/MRR, keine Fremdwhrg

tests/delivery-economics-e2e.test.js

Ein vom Kunden verfasste Domain-Paket hängt sich an und tet sich wieder ab und die Kern-Fingerabdruck unverändert bleibt

Das Gerüst schreibt ein sauberes leeres Paket und nichts anderes; kein Registry, keine Veröffentlichung, keine Sandbox – Paketnotter läuft mit den Rechten des Hosts

tests/package-contract.test.js, tests/custom-package-e2e.test.js

accordo package scaffold <name> – ein minimales, leeres, konformes lokales Paket, atomar geschrieben, standardmäßig mit Dryrun

erfindet keine Geschäftslogik, compoziert nichts, prüft weltweit keine Einzigartigkeit von Texten und installiert nichts

tests/package-scaffold.test.js, tests/package-test-command.test.js

crm app inspect – ein deterministischer, quell-geprüfter JSON-Bericht mit dem Inhalt einer Anwendung

öffnet nie die Datenbank, nimmt keinen Kontakt zu einem Anbieter auf und liest keine Geheimnisse – sondern dann sagt es in der eigenen Ausgabe

tests/app-inspect.test.js

crm solution check – ein Lösungsplan ist ein eingeheckter Vertrag mit kanonischen Fingerprint

ein Dokumentvertrag, kein Planer und keine Laufzeit; führt keinen Plan aus

tests/solution-plan.test.js

crm scenario run – zwei eingecheckte Szenarien laufen gegen echte, real zusammengestellte Anwendungen und sie zeigen, welche JTBD-Zeilen sie verdient haben und welche nicht

Coverage wird von einem Szenario behauptet, nicht entdeckt; es fördert keine Zeilen oder Browser und jede Lauf (eine\nZ), steht für eine Lösungszusammensetzung

tests/scenario-run.test.js

Generierte Moduln entwickeln sich durch explizite Revisionen und nur anfügen, datieren mit namen

Quell- oder: welche Version in einer konkreten Datenbank ist von hier nicht erkennbar

tests/module-evolution.test.js

Die gesamte Testsuite läuft bei jedem Push, zusammen mit einem Rauchtest. Wie viele Tests das ist, und an welchem Commit sie gemessen wurde, steht in site/claims.json – unter measuredAgainst. Das ist der einzige Ort in diesem Repository, an dem eine Testzahl niedergeschrieben ist. Und der einzige, in dem npm run gtm:check eine Zahl erscheinen lassen darf.

Ausführen

Node.js Version 16 oder neuer. Es gibt keine Laufzeit-Abhängigkeiten von Drittanbietern und keinen Build-Schritt.

npm run tour     # compose the whole application and inspect it
npm run verify   # source checks, then the whole test suite
npm run falsify  # break five rules on purpose and watch the suite catch them
npm run demo     # the approval slice, end to end
npm run dev      # http://localhost:4000

npm run tour ist der schnellste Weg, zu sehen, was das wirklich ist. Die Standard-Komposition des Repositorys ist bewusst leert – ein Projekt schreibt selbst die Zusammensetzung, die es will – deshalb meldet crm app inspect auf einem frischen Klon nichts. Die Tour führt den Starter-Installer (der gleiche) und wie er den jede Push in CI läuft) in ein eigenes Verzeichnis aus und inspiziert dann das Ergebnis:

  modules       76        resources     71        policies       7
  packages       9        actions       64        providers      1

  production posture — local development only: no authentication, tenancy or RBAC
                       exists, and actor headers are not identity

Es endet mit den elf Dingen, die der Inspektor nicht sehen kann, denn eine Tour, die nur die gute Hälfte zeigt, ist es nicht wert, durchgeführt zu werden. npm run tour -- --keep ./demo lässt das Projekt zum Erkunden zurück; --json gibt eine maschinenlesbare Quittung aus.

npm run falsify ist die Gegenrichtung. Eine Testanzahl sagt, wie viel geschrieben wurde; sie sagt nicht, was schiefgehen müsste, damit ein Test grün bleibt. Also entfernt dieser Befehl jeweils eine Regel – den Schutz für menschliche Akteure bei Genehmigungen, die Grenze der Genehmigungsschwelle, die Webhook-Signaturprüfung, die Unveränderlichkeit der Richtlinienversion, die Regel, dass ein vollständig verwaltetes Modul keinen öffentlichen Schreibzugriff erzeugt –, führt die Suite aus, die sie verteidigen soll, und nennt den Test, der sie gefunden hat. Er weigert sich, über nicht committete Änderungen zu laufen, und stellt jede Datei wieder her, die er berührt. Alles, was überlebt, wird als Lücke ausgegeben, denn das ist der nützliche Output (docs/FALSIFY.md, tests/falsify.test.js).

npm run demo erstellt zwei Verlängerungen und wird bei jedem Push von scripts/smoke.js geprüft:

  • 20.000 € → geht direkt in den Vorschlag über.

  • 80.000 € → bleibt in „Genehmigung ausstehend“, bis eine Führungskraft entscheidet.

Verwendung durch einen Coding-Agenten

Claude Code liest CLAUDE.md, .mcp.json und .claude/skills/. Codex liest AGENTS.md und .codex/config.toml. Beide sind eingecheckt und miteinander verbunden.

Read AGENTS.md, PRODUCT.md and docs/PROJECT_STATUS.md.
Run npm run crm -- app inspect --json.
Tell me which parts of my commercial process this already supports, and which it does not.

Ein Harness braucht nur: einen Befehl ausführen, stdout lesen, den Exit-Code lesen, JSON parsen und Dateien lesen und schreiben. Kein MCP-Server, kein Netzwerk, keine Anmeldedaten, keine Datenbank, kein langlebiger Prozess – docs/AGENT_HARNESS_COMPATIBILITY.md.

npm run crm -- app inspect --json          # what this application contains
npm run crm -- solution check plan.json    # is this plan still valid against it

Exit-Codes sind der Vertrag: 0 gültig · 1 Probleme, Bericht wird trotzdem gedruckt · 2 nicht lesbar.

Der MCP-Server läuft über stdio (node --no-warnings packages/mcp/bin/server.js) und bietet Projektinspektion, Opportunity-Auflistung, Stufenwechsel-Anfragen, Genehmigungsentscheidungen, Laufspuren und Modulgerüst. Code-erzeugende und destruktive Werkzeuge sind Trockenlauf, es sei denn, du übergibst ein explizites Apply-Flag (tests/mcp.test.js, tests/scaffold.test.js – docs/MCP.md). Er ist nur stdio und nur lokal: Es gibt keinen gehosteten oder authentifizierten MCP-Endpunkt, und der Server erbt die Autorität des Prozesses, der ihn startet.

Wo es aufhört

Lies das, bevor du irgendetwas oben bewertest. docs/benchmarks/CRM_JTBD_MATRIX.md verfolgt jeden CRM-Job mit einem konservativen Statusvokabular, in dem nicht unterstützt der Standard ist und Belege erforderlich sind, um es zu verlassen.

  • Keine Authentifizierung, kein Mandant und keine RBAC. Der Server ist nur für die lokale Entwicklung gedacht; ein Actor-Header ist eine Behauptung, keine Identität. Setze ihn nicht einem Netzwerk aus.

  • Nur SQLite. PostgreSQL ist auf der Produktions-Spine-Spur und nicht implementiert.

  • Der Build-Benchmark wurde nicht ausgeführt. Es gibt keine „Successful Agent Build Rate“. Jeder Prozentsatz, der diesem Projekt zugeschrieben wird, ist erfunden – docs/strategy/CRM_BUILD_BENCHMARK.md ist das Protokoll, kein Ergebnis.

  • Kein Scheduler, keine Erinnerungen, nichts auf einem Timer. Folgeaufgaben und eine Aktivitätszeitleiste existieren als ein gemeinsames Modell (docs/WORK_TASKS.md), und eine Person bewegt jede einzelne davon: Ein Fälligkeitsdatum ändert keinen Zustand, nichts Wiederkehrendes existiert, nichts wird zugewiesen oder benachrichtigt, und Verlängerungsfristen werden aufgezeichnet und nie ausgelöst.

  • Keine E-Mail-, Kalender- oder Marketing-Integrationen. Es gibt einen Vertrag für Benachrichtigungsanbieter; kein Adapter sendet etwas an irgendjemanden.

  • Kein Import, Export, Dedupe, Merge, Massenbearbeitung, gespeicherte Ansichten oder globale Suche. Grundvoraussetzungen in jedem kommerziellen CRM, und keine davon hat bisher einen Meilenstein.

  • Du kannst noch keine echten Kundendaten hineinlegen. Keine Authentifizierung, kein Mandant, kein Export und kein Löschpfad – daher kann eine Anfrage auf Zugriff oder Löschung einer betroffenen Person damit nicht bedient werden. docs/strategy/DATA_GOVERNANCE.md ist nur Design. Das Einzige, was gilt: Lead-Scoring ist deterministisch, versioniert und erklärbar, nicht das Urteil eines Modells über eine Person.

  • Das ist ein Framework, kein Produkt, für das du dich anmeldest. Es gibt kein gehostetes CRM, keine kostenlose Stufe, kein Konto. Das Ergebnis ist eine Anwendung, die du ausführst.

  • Eigentum bedeutet vendorisierte Quelle: Es gibt keine Framework-Abhängigkeit, die du erhöhen müsstest. npm create accordo – das veröffentlichte create-accordo@0.1.0 – erstellt ein Projekt, das startet, valid von app inspect meldet und mit 0 von project doctor beendet wird, indem es die Framework-Quelle hineinkopiert; derselbe Bootstrap läuft auch von einem Checkout (node packages/create-accordo/bin/create-accordo.js <dir> --apply, keine Installation, kein Netzwerk – tests/project-bootstrap.test.js). Was die Registry dir gibt, ist der Scaffolder, nicht das Framework: Das accordo-Paket ist eine absichtlich leere 0.0.1-Namensreservierung. Das Framework ist in das Projekt eingebettet, also besitzt du das Ergebnis vollständig – und ein Upgrade bedeutet Zusammenführen, nicht eine Version erhöhen.

Architektur in fünf Ordnern

packages/core/        the runtime platform: registry, services, workflow engine, audit
packages/modules/     CRM domain primitives
packages/domains/     optional domain packages (contracts, delivery) on a public contract
packages/mcp/         tools and context exposed to coding agents
apps/                 API server and generated Admin

Der Agent schreibt nie in eine Datenbanktabelle. Er ruft Servicemethoden und benannte Workflows auf, die Validierung, Akteuridentität, Richtlinie, Spur und Audit bewahren – ARCHITECTURE.md.

Dokumente

Lies das

Wofür

AGENTS.md

die Regeln, die ein Agent befolgen muss, bevor er Code ändert

PRODUCT.md

was das Produkt ist und was nicht

ARCHITECTURE.md

das technische Modell und seine Erweiterungsregeln

DECISIONS.md

das Entscheidungsprotokoll, ADR-001 … ADR-020

docs/PROJECT_STATUS.md

was heute im Repository wahr ist

docs/benchmarks/CRM_JTBD_MATRIX.md

jeder CRM-Job, sein Status und seine Belege

docs/QUALITY_GATES.md

die Review-Disziplin, einschließlich der Kategorien für adversariale Reviews

docs/strategy/MASTER_PLAN.md

Kategorie, Positionierung, Roadmap, Metriken

docs/strategy/GO_TO_MARKET.md

wie das Menschen erreicht und was auf einen Menschen angewiesen ist

Lizenz

MIT, bestätigt durch ADR-023.

Available Tools

3 tools
check_jobCheck Whether the Framework Does a JobA
Read-onlyIdempotent
Inspect

Answer "can this framework do X?" against the CRM jobs-to-be-done index. Returns the matching jobs with their status (not supported / partially supported / technically supported / validated end to end), the tests that prove them, and an explicit answer when the truth is that the job is not supported.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYesThe job in plain words, or a JTBD id such as JTBD-CO-01.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing output semantics: it returns statuses (not supported / partially supported / technically supported / validated end to end), supporting tests, and an explicit answer when not supported. This goes beyond annotations to set expectations about the response shape and edge-case handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The two-sentence description is dense with information, front-loading the core question and then detailing the output types. It is not overly verbose and conveys a lot in few words. A slight deduction for not being even more compact, but it remains appropriately sized for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only query tool with one required and one optional parameter, the description explains what the tool returns, including the status taxonomy and the explicit handling of unsupported jobs. It mentions tests as evidence, which provides completeness. There is no output schema to compensate for, so the description covers the essential aspects, though it could have mentioned pagination or limit behavior, which is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents 'query' fully, including an example, and 'limit' with constraints. Description coverage is 50%, and the description does not elaborate on parameters, but the schema already covers the main fields. The phrase 'against the CRM jobs-to-be-done index' adds retirement domain context to the query parameter. However, 'limit' remains semantically thin, and no new parameter information is provided in the description, so it neither helps nor hurts beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Answer') and identifies a precise resource ('the CRM jobs-to-be-done index'). It clearly differentiates the tool by describing the query format ('can this framework do X?') and enumerates the kind of results (jobs with statuses, tests, explicit answer for unsupported). This distinguishes it from generic search or capability tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use clear: answering capability questions about a framework against a CRM index. However, it does not explicitly mention when to use this over siblings like get_capability or search_docs, though the specialized index and status taxonomy imply a niche. It lacks explicit exclusions or alternative guidance but provides clear contextual usage.

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

get_capabilityGet a Capability and Its LimitationA
Read-onlyIdempotent
Inspect

Resolve a capability from the claims ledger by id (C-nn), by standing-limitation id (L-nn), or by topic. Every capability is returned together with the evidence that proves it and the limitation that bounds it — this tool cannot return one without the other.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoA claim id such as C-01, or a standing limitation id such as L-01.
limitNo
topicNoFree text, when the id is unknown. Matches claims and limitations.

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: every capability is returned with its proving evidence and bounding limitation, and the tool cannot return one without the other. This is useful but does not describe not-found behavior or other edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the first sentence stating purpose and lookup modes. The second sentence adds a valuable invariant, though the dash clause 'this tool cannot return one without the other' slightly restates the preceding point rather than adding new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple read-only lookup: it identifies resource, lookup modes, and a key return invariant. However, with no output schema and one undocumented parameter (`limit`), it should clarify parameter interaction and behavior when no capability is found; it also does not offer guidance relative to the sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%; id and topic are documented in both schema and description, but the description adds little beyond what the schema already provides. The `limit` parameter is not explained semantically, and the description does not clarify whether id and topic are mutually exclusive or can be combined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Resolve' with a clear resource ('capability from the claims ledger') and names three supported lookup paths: claim id (C-nn), standing-limitation id (L-nn), or topic. It also distinguishes this from siblings like check_job and search_docs by emphasizing the claims-ledger domain and the evidence/limitation pairing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly communicates when to use the tool by specifying lookup by id (C-nn), limitation id (L-nn), or topic. It implies topic is useful when the id is unknown, though it does not explicitly name alternatives like check_job or search_docs or provide when-not-to-use guidance.

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

search_docsSearch the Framework DocumentationA
Read-onlyIdempotent
Inspect

Keyword search across this framework's documentation set (README, AGENTS, ARCHITECTURE, PRODUCT, DECISIONS and everything under docs/). Returns the file path, the nearest heading and an excerpt for each hit. Read-only; it serves documentation, never customer records.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYesWords that must all appear on the same line. Case-insensitive.

TDQS

A4.1/5.0
Behavior5/5

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

The description discloses the output format (file path, nearest heading, excerpt per hit) and explicitly labels the tool as read-only and non-customer-data, matching the annotations. No contradictions or surprises.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that conveys the essential information without unnecessary fluff. It is perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains what the tool does, what it returns, and its read-only nature. It doesn't cover edge cases or error handling, but for a straightforward search tool, this is adequate. Minor lack of detail about the 'nearest heading' concept, but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not add any information about the parameters 'query' and 'limit' beyond what is already in the schema. Since the schema already describes both parameters, the description adds no value to parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Keyword search') and specific resource ('this framework's documentation set'), listing the included document types. It distinguishes itself from sibling tools (get_capability, check_job) by focusing on documentation search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states the tool is read-only and never serves customer records, implying it should be used for documentation queries. However, it doesn't provide explicit guidance on when to prefer this tool over alternatives, though the purpose is clear enough.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcheck_job
    • First observedget_capability
    • First observedsearch_docs

TDQS

A4.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct concern: capability resolution, job support status, and documentation search. No two tools could easily be confused.

Naming Consistency5/5

Consistent verb_noun pattern (get_capability, check_job, search_docs) with snake_case throughout.

Tool Count5/5

Three tools is a compact set, each serving a clear purpose without redundancy; the count fits the narrow domain.

Completeness4/5

The tools cover the main query paths (specific capability lookup, job support checking, and doc search). A minor gap is the lack of a list-all or overview tool, but agents can likely work around it.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers