InvokePort — JSON Repair, Schema Validation & CSV for Agents

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=false) it discloses output typing ('cells stay strings'), input support ('quoted fields'), the auth scoping requirement, and a concrete attemptId/retry policy. Some of this overlaps annotation-declared traits (determinism, no external fetch), so it is strong but not fully additive.

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?

Four short sentences, purpose front-loaded, each carrying a distinct fact (format, computation model, auth, retry). Slightly telegraphic in places but no filler.

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 output schema and a nested input object, the description only gestures at the return shape ('cells stay strings') without saying how rows map to objects or how headers are used. Prerequisites and retry semantics are complete, but the output contract remains underspecified.

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 coverage is only 50% and the csv field carries no schema description, so the description's notes on cell typing and quoted-field support meaningfully compensate for that gap. It also reinforces the attemptId contract beyond the schema's own text, though it does not state size limits or header handling.

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 states a specific operation on a specific resource: built-in CSV-to-JSON conversion, with the title/name fixing the direction. It is clear what the tool does, but it never names the reverse sibling (invokeport_json_csv) to make the direction unambiguous from the text alone.

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?

It gives real operating context: free deterministic computation, no LLM or external fetch, a scoped key permitting csv-json, and an explicit retry policy for uncertain outcomes. It stops short of stating when to choose this over the sibling converters, so it is clear context rather than full when/when-not routing.

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

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

Annotations cover the safety profile (readOnlyHint false, idempotentHint true, destructiveHint false, openWorldHint false), and the description layers on materially new traits: formula-like string escaping for spreadsheet safety, changed-cell reporting, no cleaning/dedup, free deterministic computation with no LLM or external fetch, key requirements, and non-retry semantics. This is well beyond what the structured fields convey.

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?

Dense and front-loaded: purpose first, then caveats, then operational requirements. Nearly every clause carries a distinct constraint, though the back half reads as a compact list of rules and could drop a clause or two without losing information.

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 output schema, the description covers input expectations, exclusions, safety behavior, cost, auth, and retry discipline for a two-parameter tool. The main remaining gap is the 500-row input ceiling and any explicit statement of what the returned CSV artifact looks like.

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 coverage is 50% and attemptId already carries its own description in the schema. The description adds one genuinely useful constraint on 'input' by specifying rows must be flat, but omits the 500-row maxItems limit and the nested-object shape that the schema enforces.

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 and resource pair ('Convert flat JSON records to quoted CSV') with the use case ('exporting agent results') named up front. The 'flat' qualifier separates it from the structured-JSON siblings (json_schema, json_types, json_repair) and the direction of conversion separates it from csv_json.

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?

Gives explicit scope boundaries ('No cleaning or deduplication') and a prerequisite ('Requires a scoped key allowing json-csv'), plus retry discipline for attemptId. It never names the inverse sibling (csv_json) as the alternative for the opposite direction, so guidance is strong but not fully routing.

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

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

Goes well beyond the annotations by disclosing the auth requirement (scoped key allowing json-repair), the compute profile (free, deterministic, no LLM or external fetch), the return shape (valid JSON plus review warnings), and the retry contract tied to attemptId. The 'deterministic' claim is consistent with idempotentHint=true and nothing contradicts readOnlyHint=false.

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?

Four dense sentences, front-loaded with the purpose and failure modes, then return behavior, then cost/auth, then the retry rule. No filler and no repetition of schema or annotation content.

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 output schema, the description steps in to describe the return value (valid JSON plus review warnings) and its limitation. Auth, determinism, side-effect profile, and retry semantics are all covered for a 2-parameter tool.

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 coverage is 50%: attemptId is documented in the schema, but the nested input.text field has no description. The description compensates by clarifying that the payload is malformed JSON text and by adding non-obvious semantics for attemptId (fresh ID per intended call, never auto-retry an uncertain result).

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 (Repair) and resource (malformed JSON from LLM outputs) and enumerates the concrete failure classes it handles (missing quotes, trailing commas, code fences). This is clearly distinct from sibling converters/validators like invokeport_json_csv or invokeport_json_schema.

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 gives clear context for when it applies (LLM-generated malformed JSON) and a scoping caveat (syntax repair does not recover missing facts). It does not, however, name an alternative sibling such as invokeport_json_schema for validation or state explicit exclusions, so it stops short of a 5.

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

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

Goes beyond the annotations by disclosing the auth scope requirement, the absence of network/LLM access, and a retry policy ("fresh attemptId for each intended call; never automatically retry an uncertain result") that the schema's attemptId description only partly covers. The one unexplained tension is readOnlyHint=false on what is described as a pure "free deterministic computation" — the description never says what non-read-only side effect (metering/ledger) that hint implies.

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?

Front-loaded with what the tool does and its hard limits, then cost/determinism, then auth, then retry policy — each sentence carries distinct information. It is dense (three clauses packed into the first sentence) but no sentence is filler.

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 output schema, the description still never indicates what a call returns (a boolean, a validity verdict, a list of schema violations) or how failures are surfaced — the central question for a validation tool. Coverage of limits, auth and retry is good, but the return-shape gap leaves the definition incomplete for its complexity.

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 50% (only attemptId is documented in-schema), and the description reinforces attemptId semantics (fresh ID per call, do not retry) but says nothing about the structure of the required `input` object — that it must contain `schema` and `value` must be inferred from the tool name. Baseline 3 fits: some added value, but the undocumented half of the parameters is not fully compensated.

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+resource ("JSON Schema validation") and immediately bounds the capability: "bounded structural subset; no code, regex, references, composition or network." That scope statement distinguishes it implicitly from sibling validators/converters like invokeport_json_types and invokeport_json_repair, though those siblings are never named.

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 exclusions ("no code, regex, references, composition or network") effectively tell the agent when this tool will not suffice, and the auth note ("Requires a scoped key allowing json-schema") is a precondition an agent must know. It stops short of routing to an alternative sibling when the subset is too narrow, so it is clear context rather than explicit when/when-not/alternatives.

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

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

Goes meaningfully beyond the annotations by disclosing that this is free deterministic computation with no LLM or external fetch, that the output is sample inference rather than a verified contract, and that a scoped key permitting json-types is required. The attemptId/retry instruction adds real behavioral context about non-refreshable calls.

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?

Four short sentences, front-loaded with what the tool produces before moving to caveats and operational constraints. The attemptId/retry sentence partly duplicates the schema's own description, which is the only real slack.

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 output schema, the description must carry the return-value burden; it names the artifacts (TypeScript and JSON Schema) but does not describe their structure, how mixed types or optional fields are rendered, or error behavior. The auth requirement and the 'not a verified contract' caveat are covered, so it is adequate but incomplete.

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 coverage is only 50% and the nested input object (samples, typeName) carries no schema descriptions. The description partially compensates by framing the input as 'examples' with 'optional fields and mixed types', but it never explains typeName or the samples structure, leaving the nested parameter underspecified in both places.

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 states a concrete verb+resource: converting JSON examples into TypeScript types and JSON Schema, and notes its inference-based nature. It does not, however, distinguish itself from the sibling invokeport_json_schema, which plausibly produces overlapping output, so an agent must guess at the boundary.

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?

It gives operating instructions (fresh attemptId per intended call, never auto-retry an uncertain result) but no when-to-use or when-not-to-use guidance relative to invokeport_json_schema or the other siblings. Usage context is implied by the input shape rather than stated.

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

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

Goes well beyond the annotations: it declares the computation is free and deterministic, that there is no LLM or external fetch, that a scoped key is required, and defines an explicit no-auto-retry/attemptId policy. Note the mild tension with readOnlyHint=false for what reads as a side-effect-free static check, but nothing is explicitly contradicted.

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?

Four tight sentences with the purpose front-loaded, then cost/determinism, then auth, then retry policy. Each sentence carries distinct information with no padding.

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 annotations covering safety hints and no output schema, the description is nearly complete for a read-style check: purpose, auth, determinism, and retry behavior are all present. The remaining gap is the undocumented structure of the nested input payload.

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?

At 50% schema coverage the description must help, and it does reinforce attemptId semantics (fresh per intended call, retain on uncertain outcomes). However it says nothing about the nested payload fields (openapi, paths), leaving half the parameters undocumented in both schema and description.

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 and resource: a static check of OpenAPI 3.0/3.1 authentication and transport declarations. The domain is unambiguous and naturally distinct from the json/csv/webhook siblings, though it never explicitly names or contrasts them.

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?

Gives operational guidance ('Requires a scoped key allowing openapi-security', supply a fresh attemptId, never auto-retry) but never states when to choose this over sibling checks or what prerequisite spec state is needed. Usage is implied by the purpose rather than stated.

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

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

Adds substantive behavior beyond the annotations: no delivery or signature verification, no LLM or external fetch, deterministic cost-free computation, and an explicit no-auto-retry policy. This complements openWorldHint=false, idempotentHint=true and destructiveHint=false. It does not explain the non-read-only stance (readOnlyHint=false) for what reads as a pure validation call, leaving a mild unexplained tension.

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?

Six short sentences, front-loaded with the action, then scope exclusions, then key requirements. Each sentence carries information; the attemptId sentence is slightly compressed but not wasteful.

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 output schema, the description usefully discloses the return signal (failing JSON-pointer paths) and the no-side-effect boundary. Gaps remain around the accepted schema format and success-case output, but for a 2-parameter tool this is close to complete.

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 coverage is only 50%, and the description adds little about parameter shape: it clarifies the 100-payload cap (already in maxItems) and gives attemptId lifecycle guidance that aligns with the schema note. Critically, 'bounded structural schema' is never explained (which schema dialect/subset is accepted), nor are payload requirements beyond the count.

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 and resource: 'Validate up to 100 supplied payloads against a bounded structural schema', plus the concrete output ('failing JSON-pointer paths'). It also draws scope boundaries ('no webhook delivery or signature verification'), but never names or contrasts with the closely related sibling invokeport_json_schema, leaving sibling differentiation to inference.

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?

It gives operating guidance for the attemptId ('supply a fresh attemptId for each intended call; never automatically retry an uncertain result') and implies use when you only want structural validation, not delivery. However, it never states when to pick this over invokeport_json_schema or the other JSON siblings, so alternative-selection is left implicit.

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