ek9_query_tool_detail

Returns one tool's entry - status, match (exact|single|ambiguous|none), then whenToUse, whenNotToUse, description, examples and inputSchema - by name, intent phrase or the error code it remediates.

Category: Enquiry

When to use it

'How do I call ek9_x / which tool does Y' is one call with tool:'ek9_x' or an intent phrase ('find a class by name'). Pass errorCode:'E11066' instead for the tool that remediates a diagnostic; the answer is its when-to-use, parameters and schema before you invoke it.

When not to use it

• The whole tool inventory - use ek9_query_tool_catalogue.
• A named tool SEQUENCE (release, feature_branch_start) - use ek9_query_workflow.
• An error code's diagnosis rather than its remediating tool - use ek9_explain_error.

Details

Branch on match: 'exact' (a registered name, before or after normalisation - lower case, 'ek9 '/'ek9_' stripped, spaces to '_') and 'single' (fuzzy winner: top score >= 1.5x the runner-up, the sole candidate, or the one tool whose name tokens all appear in the phrase) carry the full tool object; 'ambiguous' carries ranked candidates[] without schemas; 'none' is status:not-found with nextStep. verbosity: 'full' (default) = the JSON schema; 'summary' = parameters[] (name, type, required, enum); 'none' = name, whenToUse, description only. idePrecedent / rules / workflows are omitted when empty. Static read of the in-process registry + BM25F index - works before any user code is parsed.

Arguments

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

Phrase with repeated word

Request

{
  "tool" : "extract a statement range into a new pure function with explicit parameters and return, then replace the block with a call"
}

Response

{
  "candidates" : [ {
    "description" : "Inserts the new method (parameters and return inferred from variable data-flow) and replaces the block with a call to it; answers status, edits[] and summary, an ambiguous or boundary-crossing block as conflicts[].",
    "name" : "ek9_extract_method",
    "score" : 17.848139287413737
  }, {
    "description" : "Rewrites the declaration and EVERY call site atomically (add / remove / reorder parameters, change the return type, toggle 'as pure'); answers status, edits[] and summary with the call-site count, a blocking call site as conflicts[] (callsite-incompatible-with-new-signature).",
    "name" : "ek9_change_signature",
    "score" : 12.912289698994703
  }, {
    "description" : "Folds a contiguous line range under an if / if-else / try-catch / try-catch-finally / for-range / while head, re-indenting the block per EK9's brace-free rules; answers status and edits[] (one REPLACE carrying the head + the re-indented lines, one DELETE per absorbed line).",
    "name" : "ek9_surround_with",
    "score" : 9.385325655078438
  }, {
    "description" : "Appends a new parameter to the enclosing method/function, replaces the selected in-body expression with it and passes the ORIGINAL expression at every call site (Fowler \"Introduce Parameter\"); answers status, edits[] and conflicts[] (value-expression-not-a-single-expression, type-not-inferable, ...).",
    "name" : "ek9_introduce_parameter",
    "score" : 7.639133477618231
  }, {
    "description" : "Splices EK9 statement(s) into a named method/function/operator body at anchor top, bottom, replace or a body line, re-indented by the tool; answers status, edits[] (one INSERT), insertedLineRange and resultingBodySnippet, or error.problems[] naming the entry that does not parse.",
    "name" : "ek9_insert_statements",
    "score" : 7.535563927934353
  } ],
  "match" : "ambiguous",
  "meta" : {
...

Cut short here: 5 more lines. The whole recorded call.

Normalised phrase summary shape

Request

{
  "tool" : "edit file",
  "verbosity" : "summary"
}

Response

{
  "match" : "exact",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "note" : "Resolved 'edit file' -> 'ek9_edit_file'",
  "status" : "ok",
  "tool" : {
    "description" : "Answers first: status (applied | ready | would-fail | conflicts), written, edits[{file, startLine, endLine, before, after}], wouldBeDiagnostics from the verifying compile and contentHash on an applied edit - an atomic batch of text edits to one file, or to several as one apply.",
    "examples" : [ "{path:'orders/constants.ek9', edits:[{mode:'find-replace', find:'MAX_RETRIES <- 5', replace:'MAX_RETRIES <- 10'}], dryRun:true} → status:ready (default expectedOccurrences=1 verifies exactly one match).", "{path:'notes.md', edits:[{mode:'regex-replace', pattern:'// TODO\\\\(.*?\\\\): ', replace:'// TODO: ', expectedOccurrences:'all'}]} → status:applied with a non-ek9-file-not-compile-checked advisory." ],
    "name" : "ek9_edit_file",
    "parameters" : [ {
      "name" : "dirtyOverlay",
      "required" : false,
      "type" : "array"
    }, {
      "name" : "dryRun",
      "required" : false,
      "type" : "boolean"
    }, {
      "name" : "edits",
      "required" : false,
      "type" : "array"
    }, {
...

Cut short here: 37 more lines. The whole recorded call.

Exact match shape

Request

{
  "tool" : "ek9_add_field"
}

Response

{
  "match" : "exact",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "ok",
  "tool" : {
    "description" : "Inserts the field declaration at the construct's canonical field position; answers status, edits[] and summary, a clashing name as conflicts[] (name-collision).",
    "details" : "Two forms: structured (fieldName + defaultValue; defaultValue REQUIRED for records) or raw (rawDeclaration as typed, e.g. `name as String?` or `logger as Logger!`); mode is inferred from which is given and a contradicting mode is a conflict. Visibility is genus-fixed: class/component fields are always private, record fields always public - no access-modifier syntax exists. A pre-existing field name is a name-collision conflict (structured) or hard error (raw); an UNINITIALISED field can trip E07175/E07170 (public no-arg ctor would build a partial object) → would-fail - fix with an initialiser, a private no-arg ctor, or an explicit ctor.",
    "examples" : [ "{symbol:'CustomerOrder', fieldName:'cachedTotal', defaultValue:'Money(\"0\")', dryRun:true} → status:ready, edits[] one INSERT `cachedTotal <- Money(\"0\")` (type inferred from the default).", "{symbol:'CustomerOrder', rawDeclaration:'logger as Logger!'} → status:applied; the `!` suffix marks the field for DI injection." ],
    "idePrecedent" : "Generate Field (IntelliJ) / Quick Fix - Add Field",
    "inputSchema" : {
      "additionalProperties" : false,
      "properties" : {
        "defaultValue" : {
          "description" : "Default value expression for the field, e.g. '0', '\"\"', 'String()'. Required for records in the structured form.",
          "type" : "string"
        },
        "dirtyOverlay" : {
          "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
          "items" : {
            "properties" : {
              "content" : {
                "type" : "string"
...

Cut short here: 78 more lines. The whole recorded call.