AdCritter for Builders

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

With no annotations provided, the description carries the burden of disclosing behavior. It states that the tool returns an overview and catalog, which is clear and implies a non-destructive read operation. It also mentions how to use the returned catalog with adcritter_guidance, adding useful context beyond the bare action.

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 exactly two sentences, front-loaded with the primary instruction 'Start here when building an application'. Every sentence adds value: the first explains what the tool returns, the second gives actionable next steps with an explicit tool call and purpose.

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 zero-parameter, no-output-schema tool, the description is complete: it states the tool's role in the build workflow, what it returns, and how to proceed to detailed guides. The mention of adcritter_guidance covers the natural next step and makes the description self-contained.

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 tool has zero parameters, so the baseline is 4. The description adds no parameter-specific details because there are none, but it references calling adcritter_guidance with a key, which provides context for the overall workflow without confusing the current tool's input requirements.

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: it is the starting point for building an application, returning an overview of the platform and a catalog of feature guides. It differentiates itself from sibling tools by explicitly pointing to adcritter_guidance for detailed instructions.

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: 'Start here when building an application' and instructs the agent to 'Call adcritter_guidance(key) for any feature area'. This clearly indicates when to use this tool and directs to an alternative for further steps.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently explains the two modes (summary vs full detail) and what is returned (route, HTTP method, request/response schemas, error codes, constraints), which adequately conveys a read-only lookup operation without side effects.

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 well-structured, with a clear front-loaded purpose sentence followed by explanations of behavior and supported entities. Every sentence earns its place, with no redundancy or 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 tool with only two parameters and no output schema, the description fully covers usage modes, parameter semantics, and the content of the returned data. It includes examples and a list of valid entities, making it complete for an API reference lookup 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?

Although the schema already documents both parameters, the description adds significant meaning by explaining the effect of omitting versus passing the action parameter, and by listing concrete entity examples. This goes beyond the schema's descriptions and clarifies the interplay between entity and action.

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: 'Returns the REST API contract for an AdCritter entity.' It uses a specific verb (Returns) and resource (REST API contract), and distinguishes itself from sibling tools like adcritter_get_usage_guide and adcritter_get_platform_overview by focusing on API contract details.

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 clear guidance on when to use it: omit the action parameter to discover available actions, or pass an action for full details. It explicitly says 'use this to discover what you can do', but it does not explicitly mention alternative sibling tools or exclusions, so it slightly misses the mark on 'vs 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?

With no annotations provided, the description carries the transparency burden. It reveals the tool is format-agnostic and never prescribes frameworks or architecture, and explains the nuance of each guidance level. However, it does not explicitly state the output format (though text is implied) or clarify the discrepancy between schema default null and stated default 'full'.

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 paragraph that is moderately long but every sentence adds useful context. It front-loads the core function, then explains the guidance levels, provides an alternative, and ends with the entity list. It could be trimmed slightly as some guidance-level detail duplicates schema descriptions, but it remains efficient and logically organized.

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?

The description explains the tool's purpose, guidance levels, entity availability, and constraints (format-agnostic), which is substantial for a guidance tool with no output schema. However, it does not describe the structure or length of the returned guidance, and the lack of annotations means no safety/read-only hints are provided, leaving some gaps for a tool with no 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?

Although schema coverage is 100%, the description adds significant value by listing all available entities, which the schema only samples. It also elaborates on the meaning of guidance values beyond the concise schema descriptions, including 'softened vocabulary' and 'strong visual-design instincts', helping the agent choose appropriate parameter values.

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 returns AdCritter design guidance for a given entity, with specific content areas (screen experiences, API integration patterns, design philosophy). It also distinguishes itself from siblings by recommending alternative tools for API integration bindings, making it highly differentiated.

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?

Provides explicit when-to-use guidance for each guidance level: 'full' for step-by-step prescription, 'patterns' for balanced hints, and 'facts' for callers with strong design instincts. It also explicitly names adcritter_get_api_reference and adcritter_get_usage_guide as alternatives for API bindings, giving the agent clear decision criteria.

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, the description carries full burden. It goes beyond a simple overview by warning that tool descriptions/parameter names are conceptual and do not match actual API routes, field names, or response shapes. This is a significant behavioral caveat for the entire toolset.

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 compact and front-loaded with 'Start here.' Every sentence earns its place: overview contents, API client distinction, and pointer to the reference tool. No wasted 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?

For a zero-parameter, no-output-schema tool, the description fully explains what it returns, how it fits into the workflow, and what to do next. It is complete and even adds cross-tool context.

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 tool has 0 parameters, so a baseline of 4 applies. The description adds context about the tool's role but needs no parameter clarification since none exist.

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 'Returns the AdCritter platform overview' and lists specific contents (entity hierarchy, happy path, navigation). The opening 'Start here' distinguishes it as the entry point among 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?

'Start here' explicitly indicates when to use this tool. It also names adcritter_get_api_reference as the necessary next step before coding, providing clear alternatives and exclusions.

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, the description carries the burden. It discloses the tool returns conceptual model, relationships, and workflow rules, and enumerates valid entities. It does not describe failure behavior or output format, but for a read-only guide tool this is acceptable transparency.

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 main purpose and provides essential details in a compact form. The list of entities is necessary and keeps the description self-contained. It is slightly long but every element contributes to understanding the tool.

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?

The tool is simple (one required parameter) and the description covers what it returns, what entities are available, and what kind of guidance it provides. It does not explain the return structure, but with no output schema that is less critical. The description is sufficiently complete for an agent to invoke it 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 coverage is 100%, so baseline is 3. The description adds value by listing all valid entity values, going beyond the schema's example-based description. This fully compensates for any ambiguity in the schema and helps the agent select a correct entity.

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 returns a conceptual model and workflow guidance for an AdCritter entity, specifying what it is and how it relates to other entities. This distinguishes it from sibling tools like get_api_reference and get_design_guide, and the list of available entities makes the scope explicit.

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 says it includes 'exhaustive workflow sequencing and prescriptive rules so generated apps call the API correctly,' which implies when to use it: when you need to understand the intended workflow for an entity. It does not explicitly mention alternative tools or exclusions, but the context is clear enough for a simple guide lookup.

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, the description carries the transparency burden. It discloses the tool is read-only (returns instructions) and describes content details such as what to build, UX expectations, and API endpoints. It does not cover error behavior or authentication, but these are less critical for an informational guide 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 compact and front-loaded with the primary action. Every sentence adds value: functionality, content details, and usage prerequisite. No redundant 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?

For a single-parameter read-only tool, the description explains purpose, content, and prerequisite. It lacks explicit mention of error behavior or exact output format, but the tool is simple and the description is sufficiently 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?

The schema has 100% coverage with a clear description for the 'key' parameter. The description adds no additional semantic value beyond the schema, only repeating the source from the build_app catalog. 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?

The description clearly states the tool's function: returning detailed building instructions for a specific feature area of an AdCritter application. It distinguishes from sibling tools like adcritter_get_api_reference and adcritter_get_design_guide by focusing on build instructions and including API contracts.

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?

Provides explicit guidance to call adcritter_build_app first to obtain valid keys, establishing a clear workflow. It also implies the tool's role versus the API reference by noting it includes request/response shapes, but does not explicitly list exclusions or 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?

No annotations are provided, so the description carries the full burden. It merely states it 'returns' health/version but does not explicitly disclose that it is a read-only operation, any authentication requirements, or what the response structure entails. The word 'returns' implies non-destructive behavior, but more transparency is needed for a tool with zero annotation coverage.

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 with no filler. It conveys the essential information efficiently and is appropriately front-loaded.

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 health-check tool with no output schema, the description provides a high-level overview of the return value ('server health status and version information'). It does not elaborate on what 'health status' entails, but given the simplicity of the tool and lack of parameters, this is mostly sufficient. Slight gap in not specifying the response format, but overall complete enough.

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 tool has zero parameters, so the schema fully covers the interface. The description adds no parameter details, which is acceptable. Baseline of 4 is appropriate given no parameter complexity exists.

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 with a specific verb ('Returns') and resource ('server health status and version information'). It distinguishes itself from sibling tools like get_api_reference and get_platform_overview, which cover documentation and guidance rather than operational health.

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 intended usage is implied by the tool's nature: to check server status and version. However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. For a simple health check, this may be sufficient, but it lacks explicit usage context.

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