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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses session-scoped persistence, that enabling is additive, that unknown names are skipped while others are enabled, and that the change cannot be undone except by restarting the server.

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?

The description is front-loaded with the core action and then gives necessary context. It is a bit long but every sentence contributes useful information about usage, behavior, and limitations. There is no redundant fluff.

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 tool with no output schema, the description is complete: what it does, when to use it, how to name tools, what happens with invalid names, session scope, and how to revert. An agent has everything needed to invoke it correctly and predict its 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?

The schema already covers the parameter well, including the ['all'] special value and find_tool as the name source. The description adds useful behavioral nuance beyond the schema: unknown names are reported and skipped, the rest are enabled, and the session-scoped effect. This goes beyond the baseline but the schema does most of the semantic work.

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 clear, specific action: adding dedicated operation tools to the current session, with examples. It also distinguishes itself from the lean default tool set and from run_operation, making the tool's function unambiguous even without opening the 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 explicit when-to-use guidance: use it only when calling the same operation many times and wanting parameters spelled out. It also says 'you rarely need this' and clarifies that run_operation already handles operations, which prevents overuse. It further tells the agent to get names from find_tool.

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?

With no annotations to lean on, the description fully discloses behavior: it only recommends, never touches files, never spends credit, requires no API key, and reports no-match honestly instead of guessing. This gives an agent a complete safety and expectation profile.

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?

The description is front-loaded with the core purpose and each subsequent sentence adds a distinct fact: output contents, safety/credit behavior, cost/auth, when to use, and failure mode. There is no filler or repetition.

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 simple two-parameter discovery tool with no output schema, the description is complete: what it returns, how to phrase input, safety, cost/auth, alternatives, and no-match behavior are all covered. Nothing an agent needs to safely invoke it is left to guesswork.

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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by expanding query semantics: plain-language tasks, English or German, multiple examples, and the kind of intent that fits this tool rather than run_operation.

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 action ('Find the right bigapi operation') with a clear resource and task scope, and grounds it with concrete examples. It also distinguishes itself from sibling run_operation by making clear it is a recommender, not an executor.

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?

Explicitly says when to use it ('Start here whenever you are unsure which operation fits') and when to skip it ('skip it when you already know the operation name'). It also names the alternative execution path via run_operation and notes it is free, easing trial use.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses that the tool creates a NEW key each time, stores it in a local config file, requires network access, and that the key includes 100 free operations then $0.01 per operation. It also warns that calling it again creates an additional key rather than returning the existing one, which is a critical behavioral trait.

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?

The description is dense but every sentence earns its place: it covers when to call, what it does, side effects, pricing, and the alternative. It is front-loaded with the core purpose. It could be slightly more concise, but the density is justified given the lack of annotations.

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 tool with one optional parameter, no output schema, and no annotations, the description is remarkably complete. It explains the failure mode, the side effect, the pricing model, the network requirement, and the sibling tool to use instead. An agent has everything it needs to decide whether and how to call this 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 100%, so the schema already documents the 'name' parameter. The description adds value by explaining the parameter is cosmetic only and giving an example ('claude-desktop'), which helps the agent decide whether to pass it. This goes beyond the schema's 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?

The description states a specific verb ('Get'), a specific resource ('bigapi API key'), and a clear scope ('for this machine'). It also distinguishes itself from get_balance by explicitly noting that calling it again creates a new key rather than returning the existing one, which prevents confusion with the sibling tool.

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 explicitly says when to call it ('once when no key is configured'), what happens if you don't ('other bigapi tools fail'), and what to use instead if you need to check an existing key ('use get_balance'). This is clear, actionable guidance with an explicit alternative.

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?

With no annotations provided, the description carries the full behavioral disclosure burden and does well: it labels the call as 'Read-only, free' and warns that values are 'a snapshot of this moment – the numbers move as operations run.' This conveys no side effects and the non-deterministic nature of the result, which is critical for an agent deciding whether to call it again. No contradiction with any annotations.

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?

The description is three sentences with no filler. The first sentence front-loads the core purpose, the second provides usage context and the snapshot caveat, and the third handles sibling differentiation. Every sentence earns its place, making it compact yet information-dense.

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?

Despite having no output schema or annotations, the description covers purpose, when to use it, behavioral caveats, and the specific data points returned. The tool is a zero-parameter read operation, so nothing needed is missing. The listed fields (remaining credit, free operations left, monthly cap, spend) are sufficient for agent decision-making.

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?

The input schema is empty (0 parameters), so the baseline is 4. The description adds context by specifying that the tool checks the 'currently configured' bigapi key, clarifying the implicit subject without requiring a parameter. Since there are no parameters, the description cannot add much more, but the existing added meaning is valuable.

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 'Check the bigapi key that is currently configured' and enumerates exactly what is read: remaining credit, free operations left, monthly cap, and spend. It explicitly differentiates from sibling get_access by stating it does not create keys, and from list-like tools by noting it does not list past operations. This is a precise verb+resource definition with clear sibling differentiation.

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 explicit intended triggers: 'Use it to confirm a key works, before a large batch, or when an operation reports a low balance.' It also tells the agent when not to use it by stating it does not create keys or list operations, effectively routing those needs to siblings like get_access. This is strong practical guidance beyond generic 'use this for balance.'

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?

With zero annotations, the description carries the full burden and delivers: return behavior (file result written to output_path or temp file, returned with size and content type; data result as JSON), cost model ($0.01 flat, failed calls free), data handling (processed in Germany, deleted after delivery), and a verification claim. This is unusually rich behavioral disclosure for a tool with no annotation support.

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?

About 150 words for a generic dispatcher with 5 params, no annotations, and no output schema — every sentence earns its place by covering purpose, op sourcing, file handling, output behavior, cost, sibling relationship, and data residency. Front-loaded with purpose and examples. Slightly long, and the closing 'published proof' sentence is marginally promotional, but nothing is wasted.

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 high-complexity generic executor with no output schema and no annotations, this description is remarkably complete: it explains what the tool does, how to source the op name, how uploads are referenced, what happens when output_path is omitted, what the return payloads look like for both file and data results, cost/failure policy, and the relationship to sibling tools. The only unaddressed area is explicit auth prerequisites, which the get_access sibling implies.

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 adds meaning beyond the schema: 'Uploads are local file paths' clarifies the files parameter, 'written to output_path, or to a temporary file when you omit it' explains output_path's optional behavior, and the examples ('pdf/merge', 'ocr', 'text/chunk') illustrate the op naming convention. Slightly above baseline, but it doesn't exhaustively define params semantics.

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 ('Run any bigapi operation on real files') backed by concrete examples (merge/redact PDF, OCR, convert image, chunk text, read ZUGFeRD invoice). It distinguishes itself from siblings explicitly: 'This one executor covers every operation... enable_tools only adds convenience wrappers around it,' and routes op-name sourcing to find_tool. An agent cannot confuse this with the discovery or wrapper siblings.

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 workflow guidance: 'Take the operation name from find_tool' tells the agent where the op parameter comes from, and 'enable_tools only adds convenience wrappers around it' is an explicit when-not-to-use-alternative statement establishing run_operation as the universal executor. Pricing and failure-cost statements further clarify when calls are safe to make. No decision is left to inference.

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