Flowie Developer Docs

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds useful content scope (what the walkthrough covers, including the no-signup sandbox path), but says nothing about response format, size, or whether all sections are returned by default.

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?

A single sentence that front-loads the action, identity of the content, and its audience (agents), with zero filler or restatement of the title.

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?

For a no-required-parameter, read-only docs retrieval with no output schema, the description covers what the caller will get well enough to invoke correctly. It could be stronger by noting the default behavior when section is omitted (full guide vs. index).

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 100% and the enum values are fully documented, so the schema does the heavy lifting. The description's enumerated topics loosely map to the enum (errors, revocation) but adds no syntax, default, or behavior detail for the optional section parameter, so the baseline 3 applies.

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 (return the authentication walkthrough for agents) and enumerates the exact topics covered: sandbox key issuance, scoped access delegation, error handling, revocation. This clearly differentiates it from generic siblings like docs_read_page or docs_search, which would require the agent to know the page first.

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?

Usage is implied rather than stated: the agent must infer it should call this before attempting authentication rather than searching docs. No explicit when-to-use, prerequisites, or named alternative (e.g. docs_search for non-auth topics) is provided.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the source of truth (the OpenAPI contract) and the returned field set, but says nothing about pagination/limit behavior beyond default 50 or what the raw 'openapi' format returns. Adequate but thin against an already-covered annotation set.

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?

A single tightly written sentence that front-loads the core action and output, with the optional filtering clause placed second. No filler or restated structured data.

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?

For a read-only listing tool with no output schema, the description supplies the essential shape of what comes back (method/path/summary) and the filtering capability. It stops short of explaining the materially different 'openapi' output mode, though the enum in the schema partly carries that.

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 100%, so all four parameters are documented there, making 3 the baseline. The description adds one useful nuance — the filter matches a substring of the path OR the summary — but does not clarify how that differs from the separate `path` parameter, which behaves differently depending on `format`.

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 (List) and resource (the API's operations from the OpenAPI contract) and even enumerates the returned fields (method, path, summary). This is readily distinguishable from siblings like docs_search or docs_read_page, which retrieve page content rather than endpoint inventories.

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 implies when this tool fits ('list the API's operations ... optionally filtered'), and the filter examples clarify a discovery use case. However, it never explicitly routes the agent away from docs_search or docs_read_page when looking for endpoint information, leaving the choice to inference.

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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral information by disclosing that the page is returned as markdown, which is not captured anywhere else in structured data. It stops short of noting size limits, truncation, or auth requirements.

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 sentences, zero padding, with the core action front-loaded and the input formats immediately after. Every clause carries usable 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?

For a single-parameter read tool whose annotations fully cover the safety profile and which has no output schema, the description is close to sufficient: it says what it reads and what it returns. Minor gaps remain around the sibling-name mismatch ('search_docs' vs docs_search) and invalid-input behavior.

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 100%, so the baseline is 3, but the description goes beyond the schema's terse 'Page URL or path' by enumerating the accepted forms (full URL or path) and giving concrete examples such as /reference/ and /guides/send-invoice, which clarifies that directory-style paths are valid.

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 ('Read a documentation page') and the exact return format (markdown), which separates it from docs_search. It references the sibling that supplies URLs ('search_docs'), but the name doesn't match the actual sibling (docs_search), and it never explicitly contrasts itself with docs_list_endpoints or docs_get_auth_guide.

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?

Usage is only implied through the workflow hint that the URL comes from search_docs. There is no explicit when-to-use/when-not statement and no guidance on choosing this over docs_list_endpoints or docs_get_auth_guide, nor any note on error behavior for bad paths.

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 already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the safety profile is covered. The description adds the useful detail that results include URLs and descriptions (relevant since there is no output schema), but says nothing about ranking quality, result truncation, or pagination.

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 sentences, no filler, with the return content stated first and the routing hint second. Every clause earns its place.

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?

For a two-parameter search tool with full schema coverage and annotations covering safety, the description covers purpose, return shape, and invocation ordering. Only minor gaps remain (result limits/truncation behavior, what to do with the returned URLs).

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 100%, with both query and limit documented in the schema itself. The description adds no syntax, format, or query-construction guidance beyond what the schema already provides, so the baseline 3 applies.

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 (search the Flowie Exchange API documentation) plus what is returned (relevant pages with URLs and descriptions). It is clearly distinguishable from docs_read_page and docs_list_endpoints by intent, though it does not name those siblings explicitly.

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?

"Use this first when you need to find where something is documented" gives explicit ordering guidance relative to the other docs tools, implying docs_read_page follows. It stops short of stating when not to use it or naming the alternative tools directly.

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 already mark this as a non-read-only, non-idempotent, open-world create, and the description goes well beyond them: it enumerates the return payload (apiKey with flw_test_ prefix, organizationId, seeded company with Peppol id, next steps) and discloses the isolation guarantee ('synthetic and never reaches a real network', 'no access to any real account'). That is exactly the extra context an agent needs before minting a credential.

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, front-loaded with the action and the payoff (the returned credential), followed by exactly the two caveats that matter (synthetic data, no real-account access). 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, the description properly carries the return-value burden and does so well, plus covers data-isolation and safety. It does not mention key lifetime/expiry or any rate limits, which are relevant for a credential-minting tool, so it is strong but not exhaustive.

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 100% and the single parameter's default and behavior are fully documented in the schema. The description still adds meaning by explaining that 'suggested next steps' are part of the result, which is what includeNextSteps toggles, so it earns slightly above the baseline 3.

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 opens with a precise verb+resource ('Mint a working sandbox API key') and immediately states the distinguishing constraint ('no signup and no human in the loop'). It is unmistakably distinct from the docs_* siblings, which are read/search tools.

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 makes the operating condition explicit (no signup, no human in the loop) and gives a clear prohibition ('never send real personal data to it'). It stops short of naming an alternative or an explicit when-not-to-use case, but the context for invocation is unambiguous.

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