Proximo

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

With no annotations, the description carries the full burden and delivers: it declares READ-ONLY safety, newest-first ordering, response semantics (matched/total/truncated), and a nuanced null-principal behavior that prevents misinterpretation as a blame claim. This is far beyond a typical minimal description.

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 the safety marker and core purpose, then progressively covers use cases, response metadata, edge-case behavior, and sibling contrast. Every sentence earns its place; nothing is redundant or filler despite the length.

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?

Lacking both annotations and an output schema, the description compensates by explaining the return shape (matched/total/truncated), null-principal behavior, and ordering — plus differentiating the closest sibling (audit_verify). For a 5-param read-only query tool, this is 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 covers all 5 parameters (100%), so baseline is 3. The description adds value by explaining how the filter params relate to the `matched` count and how `limit` triggers `truncated`, enriching the semantic meaning of both filter and pagination parameters beyond the schema text.

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?

Opens with 'READ-ONLY: WHO changed WHAT and WHEN' — a specific verb (read) plus resource (PROVE ledger) and scope (guest config changes and all audited actions). It clearly distinguishes itself from the sibling audit_verify by stating it READS the chain while audit_verify PROVES integrity.

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 frames usage: 'This is how you answer "who changed this guest" or "what has this caller done"'. It also gives a when-not signal by contrasting with audit_verify ('This READS the chain; audit_verify PROVES it is intact'), steering the agent to the right sibling for integrity checks.

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. It explains the core hash-chain verification, lists specific tampering scenarios it can catch, and states the environment-variable fallback. While it doesn't describe return values or side effects, the read-only verification behavior is adequately conveyed.

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 exceptionally tight: three sentences that front-load the verb and resource, then explain the optional parameter and fallback. There is no filler, and each sentence contributes directly to understanding the tool's use.

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 only one optional parameter and no output schema, the description covers the purpose, the optional parameter, and the fallback mechanism thoroughly. The only notable gap is the lack of detail about the verification result (e.g., boolean success, status message), but this is a minor omission given the tool's simplicity and the absence of an output schema.

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 expected_head's purpose, format, and fallback. The description repeats this information almost verbatim ('also catches tail truncation, a forged tail-append, or a full ledger replacement'), adding no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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 clearly specifies the verb 'Verify' and the resource 'tamper-evident audit ledger's hash chain,' with an explicit goal to 'PROVE the log is intact.' This precisely differentiates it from sibling tools like audit_entries, which likely list entries rather than verify integrity.

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 provides concrete guidance on when to pass expected_head (to catch tail truncation, forged tail-append, or full replacement) and explains the fallback to PROXIMO_AUDIT_EXPECTED_HEAD. It even contrasts with a forward-walk-only approach, giving a clear use case, though it doesn't explicitly name alternative tools.

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?

Beyond the annotation readOnlyHint=false, the description discloses critical behavioral traits: it enforces the same gates as direct calls (dry-run plan, ledger entry, token ACL) and explicitly states it is 'a smaller doorway, not a looser one', reassuring that it doesn't bypass restrictions. It also notes it can call tools not in the server's list, which is essential behavioral context not captured in annotations or schema.

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 concise and front-loaded: the first sentence states the purpose, and the second sentence supplies the key usage prerequisite and behavioral caveat. Every sentence earns its place with 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 generic dispatcher tool, the description covers all needed aspects: how to call it, where to get argument shapes, and what restrictions apply. It even anticipates the 'non-listed tool' case. The absence of an output schema is acceptable because the return value depends on the invoked tool, and the description successfully conveys that this is a dynamic forwarder.

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 provides thorough descriptions for both parameters (tool with an example and note about non-resident names; arguments with an example and instruction to get the shape from proximo_tool_schema). The tool description adds no additional parameter meaning beyond reinforcing the schema's guidance, so the baseline of 3 applies given 100% schema coverage.

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 clear verb and resource: 'Call any Proximo tool by exact name', and further clarifies it can invoke tools 'not in this server's listed tools', distinguishing it from sibling tools like proximo_read or proximo_find_tools that target specific operations. The purpose is immediately obvious and unambiguous.

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 provides a concrete prerequisite ('Get the argument shape from proximo_tool_schema first') and states that the same gates apply ('dry-run PLAN, ledger entry, token ACL'). It implies the primary use case (calling non-resident tools) but does not explicitly contrast with alternatives or state when not to use it. Still, the guidance is actionable and contextually clear.

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?

Beyond readOnlyHint=true, the description reveals meaningful behavior: the resident/non-resident tool split, keyword matching semantics ('All terms must match'), and that results feed into proximo_tool_schema. This goes well beyond the annotation and does not contradict it.

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 purpose and the critical routing decision via 'ESTATE QUESTIONS FIRST.' Each sentence carries functional weight—alternatives, workflow, and matching constraints—without fluff. The structure with line breaks aids skimming.

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?

Given the output schema exists, this description sufficiently covers what an agent needs to select and call the tool: purpose, exclusions, workflow, parameter behavior, and search semantics. The only minor ambiguity ('searchable but not') is outweighed by the strong guidance and examples.

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 0%, so the description must compensate. It clarifies the query parameter through 'keyword' and 'All terms must match' with examples ("guest power", "ceph pool", "firewall"), but it never explains limit or how the two parameters interact. Partial compensation only.

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 specific verb and resource: 'Search Proximo's full tool catalog by keyword.' It is immediately distinguishable from siblings like proximo_recall (state/memory queries), proximo_tool_schema (arguments for a specific tool), and proximo_read/proximo_call (execution). The purpose is unmistakable.

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 routes the agent: 'if the question is what exists, how many, what changed, or when something last happened, call proximo_recall instead' and 'Come here for everything else.' It also provides a concrete downstream workflow: search, then proximo_tool_schema, then proximo_read or proximo_call.

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, and the description reinforces this by stating 'READ-ONLY' and 'refuses anything that can mutate'. It adds behavioral context by mentioning the refusal behavior (it will reject mutations) and the prerequisite flow (get shape from proximo_tool_schema first). With annotations covering the read-only nature, the description goes a step further to describe refusal behavior, which is valuable.

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 two sentences, front-loading the key safety trait (READ-ONLY) and the refusal behavior, then stating the flow and routing. Every word contributes meaning; 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?

For a dispatcher tool with minimal parameters and no output schema, the description covers the essential behavior (read-only, refusal, routing to proximo_call, prerequisite schema lookup). It does not describe the return format, but the tool is a generic executor; the return depends on the called tool, which the agent can learn from proximo_tool_schema. This is sufficient for correct invocation.

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 0%, meaning the schema provides no descriptions for the parameters. However, the tool has only two parameters: 'tool' (required, a string) and 'arguments' (optional, an object or null). The description explains that 'tool' is an exact name and 'arguments' are passed to that tool. Though it does not detail the structure of arguments, it establishes the usage pattern. Baseline 3 is appropriate given the generic nature of a dispatcher tool.

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 clearly states the tool's purpose: run a read-only Proximo tool by exact name. It explicitly distinguishes itself from proximo_call (which handles mutations) by declaring 'refuses anything that can mutate (use proximo_call for those)'. This differentiates it from siblings immediately.

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 provides explicit usage guidance: it tells the agent to use this tool for read-only operations and to use proximo_call for mutating operations. It also instructs the agent to get the tool shape from proximo_tool_schema first, which is a clear when-to-use directive for the companion 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?

Beyond the readOnlyHint annotation, the description reveals that this is a snapshot from local memory, not live data, and that entries carry as_of and age_seconds stamps. It also clarifies that not_seen_since is an observation, not proof of deletion, and that journal entries are summaries only — substantial behavioral detail that the annotation alone does not 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?

The description is dense but highly efficient; every sentence and clause adds operational value. It front-loads the most important distinction (memory vs live) and uses compact, scannable phrasing like 'stamped {source:'memory', as_of, age_seconds}' and 'not_seen_since (last observed before the window — a fact, not a claim the entity is gone)' to pack maximum insight into limited text.

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?

Given the tool's complexity (optional diff windows, journal integration, memory configuration) and the presence of an output schema, the description covers the essential semantics: data freshness, server-side counting, derivation/rebuildability, and safe usage guidance. It fully equips an agent to decide when and how to invoke the tool without missing behavioral nuances.

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?

Although the schema already documents all four parameters with descriptions, the tool description adds critical cross-parameter behavior: `since` activates diffs (appeared, status_changed, not_seen_since), `journal=N` includes diagnosis digests and is windowed by `since`, `query` narrows rows but counts cover the whole estate, and `detail` controls row depth. This enriches meaning well beyond the individual schema entries.

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 'READ-ONLY: the estate map from local Tier-1 memory' which clearly identifies the resource and operation. It explicitly contrasts with 'NOT a live PVE read' and enumerates the exact return contents (counts, entity rows, stamps), distinguishing it from sibling audit and tool-discovery 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'For live state use pve_list_guests / pve_cluster_resources' while this tool serves memory-derived summaries. It also advises trusting guest_summary for guest-count questions and explains that `since` and `journal` are optional for diffs and digests, providing clear context for choosing this tool over 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?

The annotation readOnlyHint=true already covers the read-only nature of the operationunciated, and the description adds no behavioral details beyond that. It does not mention side effects or permission requirements, but the readOnlyHint is sufficient. The description's statement about returning schema is a basic behavioral description, but it doesn't add much value over the annotation.

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 a single clear sentence that is front-loaded with the key purpose. There is no fluff or repetition. It effectively communicates what the tool does in minimal words.

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?

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete. It states what it returns and where the tool name originates. While it could mention that it doesn't execute the tool, the readOnlyHint and the nature of returning a schema make that implicit. Overall, an agent would know how to use it for most cases.

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 only parameter 'name' has no description in the schema, and schema coverage is 0%. The description implies that 'name' refers to a tool found via proximo_find_tools, providing some context. However, it doesn't explicitly state that 'name' is the tool name or give format examples. It adds moderate value but could be more explicit.

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 clearly states that the tool returns the full description and JSON input schema for a tool identified via proximo_find_tools. Though it lacks an explicit verb like 'retrieve' or 'get', the purpose is unambiguous from the context of the tool name and description. It does not repeat the tool name, but the meaning is clear.

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?

No guidance is provided on when to use this tool versus its siblings, or on any prerequisites. For example, it does not mention that the tool name should come from proximo_find_tools, nor does it differentiate from proximo_read or other retrieval tools. The description simply states its function without usage context.

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