get_knowledge

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is established. The description adds meaningful behavioral guarantees beyond that: for bp-moniker it states the tool is 'Backed by names/text extracted from a real D365FO install — never invents a moniker,' which addresses hallucination risk explicitly. For error diagnosis, it promises 'structured root cause + step-by-step fix + corrected X++ example,' setting expectations for output shape. It does not contradict the annotations and provides context that is not present in structured fields, so a 4 is warranted (not 5, as it omits details like rate limits or potential failure modes, though these are less critical for a read-only tool).

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 long but every sentence earns its place. The purpose is front-loaded ('X++ knowledge lookup'), followed by a bulleted breakdown per `kind`, each with clear action verbs and usage timing. The parameter descriptions are terse yet complete, and the overall structure is scannable. There is no padding or repetition; the length is justified by the four distinct modes, and the formatting improves comprehension. This is a model of efficient technical writing.

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 10 parameters, 4 enum-driven kinds, and no output schema, the description is outstandingly complete. It details every kind's purpose, required parameters, usage timing, and examples, and even explains the rationale for op-spec (that other tools omit inline params). It also clarifies fallback behavior ('Omit topic for the index'). The only thing missing is a description of the return payload, but because it is a knowledge lookup (not an operation), the output shape is less critical and the description hints at what each kind returns (e.g., 'structured root cause + step-by-step fix'). An agent would have no difficulty calling this tool correctly.

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 per calibration the baseline is 3. The description significantly exceeds that baseline by prefixing each parameter with its applicable kind (e.g., '[knowledge] REQUIRED', '[bp-moniker validate/suppress] REQUIRED') and explaining cross-parameter relationships that the schema does not. For instance, it states 'Omit topic for the index of available topics' (not in schema), explains that `topics` 'Replaces topic' for batch lookups, and provides concrete examples for `topic` values. These additions substantially aid parameter selection beyond the raw enum/type info, so a 4 reflects the incremental value.

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 'X++ knowledge lookup' and then enumerates four distinct `kind` values (knowledge, error, op-spec, bp-moniker), each with a concrete verb+resource pairing (e.g., 'look up an X++ topic/rule', 'diagnose a D365FO/X++ compiler or runtime error', 'parameter contract for ONE d365fo_file operation'). It clearly differentiates the tool from siblings by focusing on lookup/query behavior rather than generation or execution, and the examples (e.g., 'select-statement', 'TTS mismatch') make the scope 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 gives explicit, kind-specific usage instructions: 'Use BEFORE generating code' for knowledge, 'Call this instead of guessing — X++ error semantics differ from C#/.NET' for error, 'call this after picking the operation, before the call' for op-spec, and detailed validation/search/suppress guidance for bp-moniker. It also notes that op-spec exists because 'those two tools deliberately do not ship their parameters inline,' which explains the necessity of this lookup and implicitly warns against using the tool prematurely. No exclusions are stated, but the guidance is strong enough to route the agent correctly.

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